dfirs1car1o/saas-assurance

# SaaS 保障 [](LICENSE) [](https://github.com/dfirs1car1o/saas-assurance/actions/workflows/ci.yml) [](https://www.python.org/) 针对 Salesforce 和 Workday 等商业平台的只读 SaaS 安全评估流水线，旨在从采集到治理输出的全过程中保持证据的来源完整性。  ## 项目简介 这是一个七阶段的只读 SaaS 保证流水线，由多智能体 AI 驱动，具有强制性的工具排序和 OWASP Agentic App Top 10 加固。旨在将平台配置证据转化为结构化的发现、治理输出、POA&M 就绪的补救跟踪以及可重复的监控工件。 ``` Phase 1 — Collect sfdc-connect / workday-connect → sfdc_raw.json / workday_raw.json Phase 2 — Assess oscal-assess + oscal_gap_map → gap_analysis.json + backlog.json Phase 3 — Score sscf-benchmark → sscf_report.json (RED/AMBER/GREEN) Phase 4 — Gate nist-reviewer (NIST AI RMF 1.0) → nist_review.json (clear/flag/block) Phase 5 — AICM gen_aicm_crosswalk → aicm_coverage.json Post-proc — OSCAL gen_poam + gen_assessment_results → poam.json + assessment_results.json + gen_ssp (standalone scripts — not pipeline) → ssp.json Phase 6 — Report report-gen (app-owner + security) → Markdown + DOCX governance packages Phase 7 — Monitor export_to_opensearch + dashboards → OpenSearch trending + 3 dashboards ``` **平台支持：** Salesforce (45 个 SBS 控制项) · Workday (30 个 WSCC 控制项) **框架链：** 平台控制项 → SSCF v1.0 → CCM v4.1 → ISO 27001:2022 Annex A → SOX / HIPAA / SOC2 / NIST 800-53 / PCI DSS / GDPR **AI 治理链：** SSCF v1.0 → CSA AICM v1.0.3 (243 个控制项, 18 个域) → EU AI Act / ISO 42001 / NIST AI 600-1 / BSI AI C4 **OSCAL 输出：** 已解析目录 · 评估结果 · 系统安全计划 · POA&M — 均符合 OSCAL 1.1.2 标准 **AI 治理：** 每个输出在交付前都会通过 NIST AI RMF 关口 — 区分实时采集与存根，对块裁决需要人工确认 该系统**绝不会向任何 SaaS 组织写入数据**。所有证据均保存在 `docs/oscal-salesforce-poc/generated/` 中。 ## 快速开始 无需 Docker。完全通过命令行运行，要求 Python 3.11+。 ``` git clone git@github.com:dfirs1car1o/saas-assurance.git saas-assurance cd saas-assurance python3 -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" # installs runtime + all dev/test dependencies cp .env.example .env # fill in credentials python3 scripts/validate_env.py # 快速本地验证（无需 credentials） pytest tests/test_harness_dry_run.py -v ``` **运行完整流水线 — Salesforce (实时组织)：** ``` agent-loop run --env dev --org --approve-critical ``` **运行完整流水线 — Workday (实时租户)：** ``` agent-loop run --platform workday --env dev --org --approve-critical ``` **Workday 演练运行 (无需凭据)：** ``` python3 scripts/workday_dry_run_demo.py --org acme-workday --env dev ``` **在无 API 密钥的情况下生成报告 (模拟/测试模式)：** ``` python3 -m skills.report_gen.report_gen generate \ --backlog docs/oscal-salesforce-poc/generated///backlog.json \ --audience security \ --out $(pwd)/docs/oscal-salesforce-poc/generated///report_security.md \ --mock-llm ``` ## 多智能体架构 ``` Human ──► agent-loop run (harness/loop.py) │ └──► Orchestrator (gpt-5.3-chat-latest) │ ├── 1a. sfdc_connect_collect → sfdc_raw.json (Salesforce) ├── ╰─► collector_enrich → flags (evidence QA) [agent sub-call] ├── 1b. workday_connect_collect → workday_raw.json (Workday) ├── ╰─► collector_enrich → flags (evidence QA) [agent sub-call] ├── 1.5 backlog_diff → drift_report.json (re-assessments only) ├── 2. oscal_assess_assess → gap_analysis.json ├── ╰─► assessor_analyze → flags (confidence QA) [agent sub-call] ├── ╰─► sfdc_expert_enrich → gap_analysis.json+ (if flagged) ├── ╰─► workday_expert_enrich → gap_analysis.json+ (if flagged, Workday) ├── 3. oscal_gap_map → backlog.json + matrix.md ├── 4. sscf_benchmark_benchmark → sscf_report.json ├── 5. nist_review_assess → nist_review.json (AI RMF gate) ├── 5d. gen_aicm_crosswalk → aicm_coverage.json (AICM v1.0.3) ├── 6a. report_gen_generate → *_remediation_report.md (app-owner) ├── 6b. report_gen_generate → *_security_assessment.md + .docx ├── ╰─► security_reviewer_review → flags (delivery QA) [agent sub-call] └── 6c. finish() ``` 所有智能体均为 OpenAI 模型 (`gpt-5.3-chat-latest`)。编排器将工具调用分发给技能（Python CLI）和内联**智能体子调用** — 在流水线阶段之间注入专家智能的直接 OpenAI 聊天补全。智能体通过磁盘上的 JSON 证据文件进行通信 — 无共享状态或 MCP。**工具排序通过代码强制执行**，位于 `harness/loop.py` 的 `_TOOL_REQUIRES` 中。 ### 流水线智能体 (通过 `agent-loop run` 调用) | 智能体 | 角色 | |---|---| | Orchestrator | 规划并分发所有流水线步骤 | | Collector | 审查原始证据质量；标记缺失范围和过期引用 | | Assessor | 审查差距分析置信度；标记低置信度的关键发现 | | SFDC Expert | 随叫随到的 Salesforce/Apex/API 专家，处理复杂的 `needs_expert_review` 发现 | | Workday Expert | 随叫随到的 Workday HCM/Finance 专家；为权限被拒的发现提议 RaaS 报告 | | NIST Reviewer | 验证输出；根据 NIST AI RMF 发布阻止/标记/通过裁决 | | Reporter | 为治理报告撰写 LLM 叙述 | | Delivery Reviewer | 对安全报告进行最终的交付质量检查 — 标记凭据暴露、状态虚假陈述、范围违规 | | Container Expert | Docker Compose, OpenSearch, NDJSON 仪表板, JVM 调优 | ## 技能 所有工具均为基于 CLI 的 Python 脚本。每个脚本均支持 `--help` 和 `--dry-run`。 | 技能 | 模块 | 功能 | |---|---|---| | `sfdc-connect` | `skills/sfdc_connect/` | 通过 REST 和 Tooling API 认证并查询 Salesforce | | `oscal-assess` | `skills/oscal_assess/` | 对照 SBS OSCAL 控制目录评估发现差距 | | `sscf-benchmark` | `skills/sscf_benchmark/` | 按 CSA SSCF 域对发现进行评分 | | `nist-review` | `skills/nist_review/` | NIST AI RMF 1.0 治理关口 | | `report-gen` | `skills/report_gen/` | 生成包含 AICM 附件的高管 Markdown + DOCX 报告 | | `workday-connect` | `skills/workday_connect/` | Workday HCM/Finance 采集器 — OAuth 2.0, 30 个控制项, RaaS/REST/手动 | | `gen-aicm-crosswalk` | `scripts/gen_aicm_crosswalk.py` | CSA AICM v1.0.3 覆盖交叉映射 — 243 个控制项, 18 个域；已注册智能体工具 | ### 报告结构 安全受众会生成**三份伴随文档** — 每个受众只获取他们所需的内容： **主要评估** (`report_security.md` / `.docx`)： ``` [Gate banner] ← ⛔ block / 🚩 flag if NIST verdict requires it Companion document reference ← links to annex + methodology files Executive Scorecard ← overall score + severity × status matrix Domain Posture (ASCII chart) ← bar chart of all SSCF domain scores All Assessed Controls ← every control, sorted critical→low, with action + due date Executive Summary + Analysis ← LLM narrative (risk + remediation) Not Assessed Controls ← out-of-scope appendix for auditors NIST AI RMF Governance Review ← govern/map/measure/manage function table + blockers ``` **附件** (`report_security_annex.md` / `.docx`) — 面向治理/审计团队： ``` Full Control Matrix ← complete sorted findings table Plan of Action & Milestones ← POAM-IDs, owners, due dates, Open/In Progress OSCAL Framework Provenance ← catalog → profile → component → ISO 27001 → CCM chain CCM v4.1 Regulatory Crosswalk ← fail/partial findings → SOX/HIPAA/SOC2/PCI/GDPR ISO 27001:2022 SoA ← full Statement of Applicability (all 93 Annex A controls) ``` **证据方法论** (`report_security_methodology.md`) — 面向验证采集的审计人员： ``` Per-control API queries ← exact SOQL/REST endpoint used to assess each control Collection method ← API type (REST / Tooling / Metadata / RaaS / manual) ``` ## 控制框架 所有平台控制项均通过 SSCF → CCM v4.1 → 监管交叉映射进行链接。AICM v1.0.3 为使用 AI 功能 SaaS 的组织增加了 AI 特定的治理覆盖。 | 框架 | 版本 | 配置文件 | |---|---|---| | CSA SSCF | v1.0 | `config/sscf/sscf_v1_catalog.json` (OSCAL 1.1.2, 36 个控制项, 6 个域) | | Security Benchmark for Salesforce (SBS) | v1.0 | `config/oscal-salesforce/sbs_profile.json` (SSCF 的 OSCAL 子配置文件, 45 个控制项) | | Workday Security Control Catalog (WSCC) | v1.0 | `config/workday/wscc_v1_profile.json` (SSCF 的 OSCAL 子配置文件, 30 个控制项) | | CSA CCM | v4.1 | `config/ccm/ccm_v4.1_oscal_ref.yaml` (参考；CCM 控制 ID 嵌入在 SSCF 目录中) | | **ISO/IEC 27001:2022** | **2022** | **`config/iso27001/sscf_to_iso27001_mapping.yaml`** (直接 Annex A 映射 — 93 个控制项中的 29 个；完整的 93 控制项 SoA 在安全报告中自动生成) | | NIST AI RMF | 1.0 | 由 `nist-review` 技能应用 | | **CSA AI Controls Matrix (AICM)** | **v1.0.3** | **`config/aicm/sscf_to_aicm_mapping.yaml`** (36 个 SSCF → 18 个 AICM 域；11 个已覆盖/部分, 7 个缺口；映射到 EU AI Act / ISO 42001 / NIST AI 600-1 / BSI AI C4) | ## 流水线演进 从最初的六步流水线扩展到当前的七阶段流水线的变化： ``` Original Pipeline Current Pipeline ────────────────────── ────────────────────────────────────────── 1. sfdc_connect_collect 1a. sfdc_connect_collect (Salesforce) 1b. workday_connect_collect (Workday) 1.5 backlog_diff (re-assessments only) 2. oscal_assess_assess 2. oscal_assess_assess 3. oscal_gap_map 3. oscal_gap_map 4. sscf_benchmark 4. sscf_benchmark 5. nist_review_assess 5. nist_review_assess (AI RMF gate) 5d. gen_aicm_crosswalk (AICM v1.0.3) 6a/6b. report_gen_generate 6a/6b. report_gen_generate 7. export_to_opensearch (dashboards) ``` ## 仓库布局 ``` agents/ ← Agent definitions (YAML frontmatter + role docs) config/ sscf/ ← SSCF v1.0 OSCAL catalog (36 controls, 6 domains) + profile + CCM bridge salesforce/ ← SBS v1.0 OSCAL sub-profile (45 controls) + Salesforce platform notes workday/ ← WSCC v1.0 OSCAL sub-profile (30 controls) + Workday/ISSG notes component-definitions/ ← OSCAL component definitions: evidence specs per control (Salesforce + Workday) oscal-salesforce/ ← Legacy SBS OSCAL catalog + SSCF mapping ccm/ ← CCM v4.1 reference pointer (CCM IDs embedded in SSCF catalog) iso27001/ ← ISO 27001:2022 Annex A direct mapping (36 SSCF → 29 Annex A controls) + 93-control catalog aicm/ ← CSA AICM v1.0.3 catalog (243 controls, 18 domains) + SSCF crosswalk mapping contexts/ ← System prompts for assess/review/research modes docs/ architecture.png ← Auto-generated reference architecture diagram oscal-salesforce-poc/ ← Generated evidence, deliverables, runbooks wiki/ ← Full wiki (18 pages; mirrors GitHub wiki) harness/ ← agent-loop CLI (loop.py, tools.py, agents.py, memory.py) hooks/ ← Session lifecycle scripts (start/end/compact) mission.md ← Agent identity and authorized scope schemas/ baseline_assessment_schema.json ← v2 platform-agnostic assessment schema scripts/ ← oscal_gap_map.py, generate_sbs_oscal_catalog.py, validate_env.py skills/ sfdc_connect/ ← Salesforce collector (REST + Tooling + Metadata API) oscal_assess/ ← OSCAL gap assessor sscf_benchmark/ ← SSCF domain scorer nist_review/ ← NIST AI RMF gate (--platform salesforce|workday) report_gen/ ← Governance report generator (MD + DOCX) workday_connect/ ← Workday HCM/Finance collector (OAuth 2.0, 30 controls, 21 tests) tests/ ← pytest suite (fully offline, no API keys needed) docs/security/ ← threat-model.md — OWASP Top 10 for Agentic Applications 2026 ``` ## 身份认证 JWT Bearer 是 Salesforce 唯一支持的身份认证方式。 **JWT Bearer (唯一支持的方法)：** ``` SF_AUTH_METHOD=jwt SF_USERNAME=your.name@yourorg.com SF_CONSUMER_KEY= SF_PRIVATE_KEY_PATH=/path/to/salesforce_jwt_private.pem SF_DOMAIN=login ``` ## 环境变量 有关完整参考，请参阅 `.env.example`。最低要求： ``` OPENAI_API_KEY=sk-... # Required for all LLM calls SF_USERNAME=... # Salesforce username SF_AUTH_METHOD=jwt # JWT Bearer — only supported method SF_CONSUMER_KEY=... # Salesforce Connected App consumer key SF_PRIVATE_KEY_PATH=... # Path to RSA private key (outside repo, chmod 600) QDRANT_IN_MEMORY=1 # Use in-memory Qdrant (no server needed) MEMORY_ENABLED=0 # Disable Mem0 by default ``` ## 安全 - 默认对所有 SaaS 组织只读。未经明确人工批准不得写入。 - 凭据仅从环境获取 — 绝不作为 CLI 标志传递或记录在日志中。 - 所有生成的证据写入 `docs/oscal-salesforce-poc/generated/` — 永不写入 `/tmp`。 - **工具排序在代码中强制执行** — `harness/loop.py` 中的 `_TOOL_REQUIRES` 映射阻止乱序 LLM 工具调用 (OWASP A2 Excessive Agency)。 - **输入路径验证** — 所有 LLM 提供的文件路径在子进程执行前均会根据工件根目录进行检查；组织别名限制为 `[a-zA-Z0-9_-]{1,64}` (OWASP A5)。 - **内存防护** — 注入模式在到达编排器提示之前从 Qdrant 存储的内存中剥离 (OWASP A3)。 - **结构化审计日志** — 每次运行都会将每个工具调用记录到 `audit.jsonl` (工具, 参数, 状态, duration_ms, turn) (OWASP A9)。 - AI 输出在交付前由 `nist-review` 技能验证。阻止裁决会停止报告分发。 - **所有外部 API 连接均独占使用 HTTPS** — Salesforce, Workday, 和 OpenAI SDK 在每次调用时强制执行 TLS。 - 完整威胁模型：`docs/security/threat-model.md` — OWASP Top 10 for Agentic Applications 2026, 8 项已缓解, 2 项部分缓解。 ## 开发 ``` source .venv/bin/activate ruff check skills/ harness/ # lint bandit -r skills/ harness/ # SAST pip-audit # dependency CVEs pytest tests/ -v # fully offline, no API key needed ``` CI 技术栈：ruff · bandit · Semgrep (`p/python` + `p/owasp-top-ten`) · pip-audit · gitleaks · pytest · CodeQL · grype · zizmor · CodeRabbit Pro · dependency-review。 所有 PR 均需一名审核人批准。分支保护禁止对 `main` 进行强制推送。 ## 可选：容器化技术栈 + 持续监控 如果您需要完整的容器化平台 (OpenSearch + 预构建仪表板 + Docker 中的智能体)： ``` docker compose up -d # starts OpenSearch + OpenSearch Dashboards open http://localhost:5601 # three dashboards auto-imported and ready ``` 首次启动时会自动导入三个预构建的仪表板 — 无需手动设置： | 仪表板 | URL | 用途 | |---|---|---| | **SSCF Security Posture Overview** | `/app/dashboards#/view/sscf-main-dashboard` | 综合跨平台视图 — Salesforce + Workday 并排显示 | | **Salesforce Security Posture** | `/app/dashboards#/view/sfdc-dashboard` | 仅 Salesforce 发现，SBS 季度审查 | | **Workday Security Posture** | `/app/dashboards#/view/workday-dashboard` | 仅 Workday 发现，WSCC 合规审查 | **Salesforce Security Posture 仪表板：**  **Workday Security Posture 仪表板：**  每个平台仪表板包含 **13 个面板**，均由 KQL 按平台过滤 (`platform : salesforce` / `platform : workday`)： ``` Row 1 Score tile (RED/AMBER/GREEN) · Pass count · Fail count Row 2 Top Failing Controls (horizontal bar, colored by severity) — full width Row 3 Control Status donut · Risk by Domain (stacked bar, fail/partial only) Row 4 Findings by Severity (stacked by status) · Open Items by Owner (accountability bar) Row 5 Score Over Time (trend line) — full width Row 6 Critical & High failures table — full width Row 7 POA&M open items table — full width Row 8 Failing Controls — full-width document search, sortable Row 9 Partial Controls — full-width document search with remediation notes ``` 每次评估后，导出结果以填充仪表板： ``` # live 或 dry-run assessment 后导出 python scripts/export_to_opensearch.py --auto --org --date $(date +%Y-%m-%d) # 或使用 interactive runner（自动处理导出） python scripts/run_assessment.py ``` **Docker 技术栈和仪表板是可选的** — 如果您的组织已经使用 Splunk, Elastic, Grafana 或 GRC 工具，请调整 `scripts/export_to_opensearch.py` 中的接收器以进行适配。 有关完整的面板参考和导航指南，请参阅 [`docs/wiki/OpenSearch-Dashboards.md`](docs/wiki/OpenSearch-Dashboards.md)， 有关调度，请参阅 [`docs/wiki/Continuous-Monitoring.md`](docs/wiki/Continuous-Monitoring.md)。

标签：Agent 安全, CCM v4.1, CSA STAR, CSPM, DevSecOps, HIPAA, ISO 27001, IT 治理, NIST 800-53, NIST AI RMF, OSCAL, OWASP Agentic Top 10, PCI DSS, Petitpotam, POA&M, Python, SaaS 安全, Salesforce 安全, SOC 2, SOX 法规, SSCF 基准, TinkerPop, Web报告查看器, Workday 安全, 上游代理, 云安全态势管理, 前端应用, 只读评估管道, 合规报告生成, 多智能体 AI, 安全合规审计, 安全态势监控, 对称加密, 无后门, 溯源能力, 版权保护, 自动化审计, 证据保全, 足迹分析, 逆向工具, 配置审查