# @cloud-copilot/iam-simulate 中文文档

规范地址：https://npmcn.com/package/%40cloud-copilot/iam-simulate/

版本：0\.1\.173
npm 元数据更新时间：2026-08-29T12:21:11.545Z
中文译文更新时间：2026-11-10T02:19:31.533Z
软件包许可：AGPL-3\.0-or-later

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cloud-copilot/iam-simulate
原文对照：https://npmcn.com/package/%40cloud-copilot/iam-simulate/?lang=original
项目主页：https://github.com/cloud-copilot/iam-simulate#readme
源码仓库：https://github.com/cloud-copilot/iam-simulate

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.3 MB，597 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2024-10-29T17:42:23.373Z
- 最新版本发布：2026-08-29T12:21:11.202Z
- 近 30 天下载量：26280（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：175（近 12 个月 87 个）

## 中文简介

模拟评估AWS IAM政策

## 安装

```sh
npm install @cloud-copilot/iam-simulate
```

也可以使用：`pnpm add @cloud-copilot/iam-simulate`、`yarn add @cloud-copilot/iam-simulate`、`bun add @cloud-copilot/iam-simulate`

## README

# IAM 模拟

[![NPM Version](https://img.shields.io/npm/v/@cloud-copilot/iam-simulate.svg?logo=nodedotjs)](https://www.npmjs.com/package/@cloud-copilot/iam-simulate) [![License: AGPL v3](https://img.shields.io/github/license/cloud-copilot/iam-simulate)](https://npmcn.com/package/%40cloud-copilot/iam-simulate/LICENSE.txt) [![GuardDog](https://github.com/cloud-copilot/iam-simulate/actions/workflows/guarddog.yml/badge.svg)](https://github.com/cloud-copilot/iam-simulate/actions/workflows/guarddog.yml) [![Known Vulnerabilities](https://snyk.io/test/github/cloud-copilot/iam-simulate/badge.svg?targetFile=package.json&style=flat-square)](https://snyk.io/test/github/cloud-copilot/iam-simulate?targetFile=package.json)

一个AWS IAM模拟与政策测试器被建为节点/标本库.

模拟器目前支持 AWS IAM 的这些特性

### IAM 特性支持

-   身份政策
-   资源政策
-   服务控制政策
-   资源控制政策
-   权限边界
-   全体 [AWS 条件操作员](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)
-   同一账户和交叉账户请求
-   IAM 信托政策和 KMS 关键政策自定义信任行为

### 请求验证

iam- 模拟将自动验证输入, 包括

-   采用 [政策](https://github.com/cloud-copilot/iam-policy)
-   IAM 动作使用 [iam-数据](https://github.com/cloud-copilot/iam-data)
-   相对于允许的动作资源类型的资源 ARN
-   允许动作/资源及其类型的上下文键 .

目前所有 [全局条件键](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) 允许所有不完全真实的请求。 今后将增加更多的验证.

### 解释

亚姆模拟将详细说明哪些声明在最后决定允许或拒绝请求时具有决定性意义.

它还会回复每一份被评价的语句的"解释",详细说明该语句为何适用于请求与否.

### 即将到来的特点

-   会议政策
-   验证每项行动的全球条件关键
-   从请求中自动插入上下文密钥, 如 `aws:PrincipalServiceName`

### 匿名请求

使用 `anonymousPrincipal` 以模拟未签名的请求,例如通过桶策略给予的公共 S3 对象访问。 匿名请求没有身份政策、会话政策、许可界限或SCP;这些主要侧面政策投入被 `runSimulation`。 。 。 .

```typescript
import { anonymousPrincipal, runSimulation, type Simulation } from '@cloud-copilot/iam-simulate'

const simulation: Simulation = {
  request: {
    principal: anonymousPrincipal,
    action: 's3:GetObject',
    resource: {
      resource: 'arn:aws:s3:::public-bucket/file.txt',
      accountId: '123456789012'
    },
    contextVariables: {}
  },
  identityPolicies: [],
  serviceControlPolicies: [],
  resourceControlPolicies: [],
  resourcePolicy: {
    Version: '2012-10-17',
    Statement: [
      {
        Effect: 'Allow',
        Principal: '*',
        Action: 's3:GetObject',
        Resource: 'arn:aws:s3:::public-bucket/*'
      }
    ]
  }
}

const response = await runSimulation(simulation, {})
```

### S3 块公共访问

对于S3请求,打电话者可以提供有效的 `RestrictPublicBuckets` 设置 `additionalSettings.s3.blockPublicAccess`。iam-模拟不获取或确定此设置;提供 `true` 仅当S3区块公共访问申请模拟的桶/账户时.

```typescript
const simulation: Simulation = {
  // request and policies...
  additionalSettings: {
    s3: {
      blockPublicAccess: true
    }
  }
}
```

当启用时,公共 S3 桶政策可以阻止匿名和交叉账户访问 `blockedBy: ['s3-bpa']`。 。 。 .

## 安装

```bash
npm install @cloud-copilot/iam-simulate
```

## 使用量

```typescript
import { runSimulation, type Simulation } from '@cloud-copilot/iam-simulate'

const simulation: Simulation = {
  identityPolicies: [
    {
      name: 'userpolicy',
      policy: {
        Version: '2012-10-17',
        Statement: [
          {
            Effect: 'Allow',
            Action: ['s3:GetObject'],
            Resource: ['arn:aws:s3:::mybucket/*']
          }
        ]
      }
    }
  ],
  serviceControlPolicies: [
    {
      orgIdentifier: 'ou-12345',
      policies: [
        {
          name: 'AllowAll',
          policy: {
            Version: '2012-10-17',
            Statement: [
              {
                Effect: 'Allow',
                Action: '*',
                Resource: '*'
              }
            ]
          }
        }
      ]
    }
  ],
  /*
    The default RCP `RCPFullAWSAccess` is always applied implicitly and you do not need to include it here. https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_rcps_examples.html#example-rcp-full-aws-access
  */
  resourceControlPolicies: [
    {
      orgIdentifier: 'o-123456789012',
      policies: [
        {
          name: 'EnforceSecureTransport',
          policy: {
            Version: '2012-10-17',
            Statement: [
              {
                Sid: 'EnforceSecureTransport',
                Effect: 'Deny',
                Principal: '*',
                Action: ['sts:*', 's3:*', 'sqs:*', 'secretsmanager:*', 'kms:*'],
                Resource: '*',
                Condition: {
                  BoolIfExists: {
                    'aws:SecureTransport': 'false'
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ],
  resourcePolicy: {
    Version: '2012-10-17',
    Statement: [
      {
        Effect: 'Allow',
        Action: ['s3:GetObject'],
        Resource: ['arn:aws:s3:::mybucket/*'],
        Principal: 'aws:arn:iam::123456789012:root',
        Condition: {
          StringEquals: {
            'aws:PrincipalOrgID': 'o-123456789012'
          }
        }
      }
    ]
  },
  request: {
    action: 's3:GetObject',
    principal: 'arn:aws:iam::123456789012:user/username',
    resource: {
      accountId: '123456789012',
      resource: 'arn:aws:s3:::mybucket/file.txt'
    },
    contextVariables: {
      'aws:PrincipalOrgID': 'o-123456789012'
    }
  }
}

`runSimulation` returns a discriminated union with `resultType`:

- `resultType: 'error'` includes `errors` and no simulation results.
- `resultType: 'single'` includes `overallResult` and a single `result`.
- `resultType: 'wildcard'` includes `overallResult` and `results` for each matching pattern.

const response = await runSimulation(simulation, {})
//Check for validation errors (errors are returned at the response level):
if (response.resultType === 'error') {
  console.log(response.errors.message)
  console.log(JSON.stringify(response.errors, null, 2))
}

//The simulation ran successfully
if (response.resultType === 'single') {
  const result = response.result
  console.log(response.overallResult) // 'Allowed', 'ExplicitlyDenied', or 'ImplicitlyDenied'
  console.log(result.analysis?.result)

  //Output the identity statements that allowed the request
  const identityAllowExplains =
    result?.analysis?.identityAnalysis?.allowStatements.map((s) => s.explain) || []
  //Show which statements applied and exactly how.
  for (const explain of identityAllowExplains) {
    console.log(explain)
  }
}

if (response.resultType === 'wildcard') {
  console.log(response.overallResult)
  for (const result of response.results) {
    console.log(result.resourcePattern, result.analysis?.result)
  }
}
```

这将给出一个说明,说明如何评价身份说明:

```javascript
{
  effect: 'Allow',
  identifier: '1',
  matches: true,
  actionMatch: true,
  principalMatch: 'Match',
  resourceMatch: true,
  conditionMatch: true,
  resources: [
    {
      resource: 'arn:aws:s3:::mybucket/*',
      matches: true,
    }
  ],
  actions: [ { action: 's3:GetObject', matches: true } ],
}
```

## 常见问题

### @cloud-copilot/iam-simulate 是什么？

模拟评估AWS IAM政策

### 如何安装 @cloud-copilot/iam-simulate？

在项目目录运行 npm install @cloud-copilot/iam-simulate，或使用 pnpm add / yarn add / bun add。

### @cloud-copilot/iam-simulate 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cloud-copilot/iam-simulate 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cloud-copilot/iam-simulate 可以商用吗？

@cloud-copilot/iam-simulate 使用 AGPL-3\.0-or-later 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @cloud-copilot/iam-simulate 的下载量有多少？

根据 npm 官方下载统计，@cloud-copilot/iam-simulate 在 2026/10/10 – 2026/11/08 这 30 天内被下载 26,280 次，日均约 876 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cloud-copilot/iam-simulate 还在维护吗？

最新版本 0\.1\.173 发布于 2026/08/29（2 个月前）；至今共发布 175 个版本，其中过去 12 个月发布了 87 个；首次发布于 2024/10/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。