使用 Floci 模拟 Amazon Detective组织行为图与成员生命周期 API 的本地实现指南【免费下载链接】flociLight, fluffy, and always free - The AWS Local Emulator alternative项目地址: https://gitcode.com/gh_mirrors/fl/floci导读Amazon Detective 是 AWS 面向安全治理场景的行为分析服务其核心对象是行为图Behavior Graph。Floci本地 AWS 模拟器在detective服务模块中以 REST JSON 形式实现了 Detective 的组织管理与行为图操作使本地安全治理工作流可以脱离真实 AWS 直接运行。读完本文你将掌握 Floci 中 Detective 支持的 7 个核心 Action、对应的本地 REST 端点、行为图与成员的状态机模型以及其与真实 AWS API 契约对齐的校验与错误处理细节并了解如何用 AWS SDK 在本地验证这些能力。Detective 模拟模块概览Floci 实现的 Detective 能力定位于组织管理与行为图操作这一类被本地安全治理工作流高频使用的 REST JSON 接口其官方能力声明位于 docs/services/detective.md。实现代码集中在端点与参数校验层DetectiveController.java业务逻辑与持久化层DetectiveService.java数据模型DetectiveMember.java、DetectiveState.java从源码结构看该模块采用典型的ControllerHTTP/JSON 契约→ Service业务规则 存储分层Controller 负责解析请求体、校验参数类型与范围、组织响应 JSONService 负责状态机流转、配额校验以及与组织服务OrganizationsService的联动最终状态通过AccountAwareStorageBackend按账号 × 区域持久化到detective-state.json。支持的操作一览根据文档docs/services/detective.mdFloci 的 Detective 模块共支持 7 个操作覆盖组织管理员委派与行为图成员管理两条主线ActionDescriptionListOrganizationAdminAccounts列出为组织配置的 Detective 管理员账户。EnableOrganizationAdminAccount指定 Detective 管理员账户并启用其组织行为图。ListGraphs列出当前账户与区域下的行为图。DescribeOrganizationConfiguration返回行为图的组织自动启用auto-enable设置。UpdateOrganizationConfiguration更新行为图的组织自动启用设置。ListMembers列出行为图中的组织成员账户。CreateMembers将组织账户启用为行为图成员。StartMonitoringMember让一个已接受但未启用的成员账户开始贡献数据。REST 端点与请求/响应契约Controller 层通过POST端点暴露上述能力全部请求/响应使用application/json并且不依赖固定的服务路径前缀Path(/)与 Floci 其他服务一致。端点与 Action 的对应关系如下依据 DetectiveController.javaAction本地端点请求体关键字段响应ListOrganizationAdminAccounts/orgs/adminAccountslistMaxResults、NextToken可选Administrators[].AccountIdEnableOrganizationAdminAccount/orgs/enableAdminAccountAccountId必填12 位数字空 HTTP 200ListGraphs/graphs/listMaxResults、NextToken可选GraphList[].ArnDescribeOrganizationConfiguration/orgs/describeOrganizationConfigurationGraphArn必填AutoEnable布尔UpdateOrganizationConfiguration/orgs/updateOrganizationConfigurationGraphArn必填、AutoEnable可选空 HTTP 200ListMembers/graph/members/listGraphArn必填、MaxResults、NextToken可选MemberDetails[]、NextTokenCreateMembers/graph/membersGraphArn必填、Accounts[]150 个含AccountId、可选EmailAddressMembers[]、UnprocessedAccounts[]StartMonitoringMember/graph/member/monitoringstateGraphArn、AccountId必填空 HTTP 200几点实现细节值得注意空响应体符合 AWS 契约EnableOrganizationAdminAccount、UpdateOrganizationConfiguration、StartMonitoringMember三个操作成功后返回空的 HTTP 200 响应体与 AWS API 契约一致见 DetectiveController.java 与 DetectiveIntegrationTest.java 的assertTrue(enableBody.isEmpty())断言。分页参数校验MaxResults与NextToken是分页的两个入参。ListMembers严格接受 AWS 文档规定的MaxResults范围 1200越界即抛ValidationExceptionNextToken必须是长度不超过 1024 的文本且在实际截断时解析为数字偏移量见validatePageRequest与offset方法。列表排序ListMembers返回的成员按AccountId排序保证分页结果稳定见 DetectiveService.java。行为图从委派到 ARN行为图是 Detective 的核心资源。Floci 中行为图的生命周期由EnableOrganizationAdminAccount触发只有组织管理账户organizations.describeOrganization返回的MasterAccountId才能委派 Detective 管理员被委派的账户会同时获得graphtrue的行为图见 DetectiveService.java。行为图 ARN 采用固定的确定性格式arn:aws:detective:{region}:{accountId}:graph:00000000000000000000000000000001从源码看DetectiveService.java本地环境不需要生成随机 ID而是统一使用固定的 32 位图形 ID00000000000000000000000000000001这保证了同一账号 × 区域下的图 ARN 可预测、可重复。ListGraphs会检查当前账号在请求头解析出的区域下是否存在行为图state.isGraph()存在则返回唯一的图 ARN。所有涉及图的操作DescribeOrganizationConfiguration、ListMembers、CreateMembers、StartMonitoringMember都会先校验传入的GraphArn是否与本地推导出的 ARN 完全一致不一致时返回ResourceNotFoundException——这模拟了图不存在的 AWS 行为。组织配置AutoEnable 的读写语义DescribeOrganizationConfiguration返回当前行为图的AutoEnable布尔值UpdateOrganizationConfiguration则更新它。一个容易踩坑的兼容细节是AutoEnable是可选字段——省略该字段时更新操作保持原配置不变而不是重置为false。这一点同时被单元测试omittedAutoEnableLeavesConfigurationUnchanged见 DetectiveServiceTest.java和集成测试先置true再发送不带AutoEnable的更新随后DescribeOrganizationConfiguration仍返回true见 DetectiveIntegrationTest.java双重验证。若显式传入的AutoEnable不是布尔类型Controller 会直接抛出ValidationExceptionAutoEnable must be a boolean.属于参数类型级别的严格校验。成员生命周期从 ACCEPTED_BUT_DISABLED 到 ENABLEDFloci 将行为图成员建模为两态状态机状态字段定义在 DetectiveState.java流转规则实现在 DetectiveService.javaCreateMembers创建成员成员初始状态为ACCEPTED_BUT_DISABLED。与真实 AWS 一致组织行为图下创建成员不需要邮箱地址EmailAddress可空重复创建同一账号时该账号不会出现在Members中而是以Reason: The account is already a member of the behavior graph.进入UnprocessedAccounts返回见 DetectiveController.java。StartMonitoringMember启用数据贡献仅当成员处于ACCEPTED_BUT_DISABLED状态时才能被启用为ENABLED已处于ENABLED或状态不匹配时抛出ConflictException。启用成功后成员状态变为ENABLED。ListMembers观测状态返回MemberDetails数组每项包含AccountId、EmailAddress、Status、GraphArn、AdministratorId与InvitationType: ORGANIZATION见memberNode组装逻辑DetectiveController.java。这一完整生命周期被集成测试organizationGraphAndMemberLifecycleMatchesAwsContract端到端验证创建成员 → 断言ACCEPTED_BUT_DISABLED→ 重复创建进入UnprocessedAccounts→StartMonitoringMember后ListMembers返回ENABLED见 DetectiveIntegrationTest.java。校验、配额与错误模型Floci 尽量真实地复刻 AWS Detective 的错误语义错误类型与触发条件如下错误类型__type触发条件依据ValidationExceptionHTTP 400AccountId不是 12 位数字MaxResults不在 1200NextToken非法AutoEnable非布尔Accounts数量不在 150管理员账户不在组织内DetectiveController.java、DetectiveService.javaResourceNotFoundExceptionHTTP 404行为图不存在 /GraphArn不匹配StartMonitoringMember的成员不存在DetectiveService.javaConflictExceptionHTTP 409已配置不同的管理员账户重复创建成员成员状态不满足启用前置条件DetectiveService.javaAccessDeniedExceptionHTTP 403非组织管理账户试图委派管理员DetectiveService.javaServiceQuotaExceededException行为图成员数超过 1,200 的配额上限DetectiveService.java其中 1,200 成员的配额上限在DetectiveService中以常量MAX_MEMBERS 1200定义且CreateMembers在批量创建前会先整体预检validateCreateMembers避免一次性提交的多个新成员使总量超限。文档同时明确Provider 侧的内部错误与限流错误不会被人为注入因此本地行为不会掺杂虚假的 5xx。与 AWS SDK 的兼容性验证除了服务端单元测试与 REST 集成测试仓库还提供了跨语言 SDK 兼容性测试来证明契约对齐。例如 Java SDK 侧 DetectiveOrganizationAdministrationTest.java 直接使用software.amazon.awssdk.services.detective.DetectiveClient依次执行listOrganizationAdminAccounts→enableOrganizationAdminAccount→listGraphs→updateOrganizationConfiguration→describeOrganizationConfiguration→createMembers→ 重复createMembers断言UnprocessedAccounts→listMembers→startMonitoringMember后断言状态为ENABLED完整覆盖了组织管理与成员生命周期两条主线且测试通过assumeFalse(TestFixtures.isRealAws())避免污染真实 AWS 环境。这意味着只要把 SDK 客户端指向本地 Floci 实例开发者便可以在 CI 或本地开发环境中复现这套与真实 AWS 一致的调用序列用于安全治理工作流的离线开发与回归。状态持久化与重置Detective 的状态以账号 × 区域为维度隔离存储AccountAwareStorageBackend底层落盘为detective-state.json字段包括管理员账户 ID、行为图标记、AutoEnable配置与成员映射。DetectiveService实现了Resettable接口的clear()方法可一键清空全部 Detective 状态便于测试隔离见 DetectiveServiceTest.java 的clearRemovesAllDetectiveState用例。小结Floci 的 Detective 模块以 7 个 Action 覆盖了本地安全治理工作流中最常用的组织委派与行为图成员管理场景确定性行为图 ARN、ACCEPTED_BUT_DISABLED → ENABLED成员状态机、可选AutoEnable语义、严格的分页与账号格式校验以及ValidationException/ResourceNotFoundException/ConflictException/ServiceQuotaExceededException的完整错误模型都通过单元测试、REST 集成测试与 AWS SDK 兼容性测试三重验证。对于需要离线演练 Detective 组织管理流程的团队这是一个可直接投入使用的本地替代方案。【免费下载链接】flociLight, fluffy, and always free - The AWS Local Emulator alternative项目地址: https://gitcode.com/gh_mirrors/fl/floci创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考