saisravan909/nodearmor

## 目录 | 章节 | 内容概要 | |---------|-------------------| | [独特之处](#what-makes-nodearmor-different) | 为何这不是又一个扫描器 | | [工作原理](#how-it-works) | 完整执行流程 | | [架构](#architecture) | 开放客户端 + 私有引擎信任模型 | | [快速开始](#quick-start) | 5 分钟内运行 | | [GitHub Actions 集成](#github-actions-integration) | 即插即用的 CI/CD 工作流 | | [配置](#configuration) | 所有配置选项说明 | | [检查内容](#what-gets-checked) | 所有执行检查项 | | [NIST 800-207 对齐](#nist-sp-800-207-alignment) | 零信任支柱映射 | | [行业用例](#sector-use-cases) | 联邦、国防、医疗、金融 | | [信任模型](#trust-model-open-client--private-engine) | 为何引擎是私有的 | | [性能](#performance) | 与传统流程的速度对比 | | [常见问题](#faq) | 常见问题解答 | ## 独特之处 大多数安全工具都是被动观察者。它们进行扫描。它们生成报告。它们等待人类采取行动。在压力下、实时部署中、凌晨 2 点——人类会犯错误。 NodeArmor 完全消除人类参与决策。 | | 传统安全工具 | NodeArmor | |---|:---:|:---:| | **方式** | 扫描并报告 | 执行并决定 | | **需要人工审核** | 是——始终需要 | 否——门禁自行决定 | | **检测时间** | 24–72 小时 | 30 秒以内 | | **威胁响应** | 发送警报 | 锁定流水线 | | **SBOM 执行** | 手动 | 自动化，符合 EO 14028 | | **来源验证** | 可选 | 每次构建强制执行 | | **复杂威胁响应** | 警报，祈祷 | 门禁 + 主动欺骗层 | | **NIST 800-207 对齐** | 部分 | 全部六个支柱 | | **所需依赖** | 数十个 | 零个（仅 Python 标准库） | | **成本** | 企业许可 | 免费 | ## 工作原理 ``` flowchart TD A([Developer pushes code]) --> B[GitHub Actions triggers NodeArmor Gate] B --> C{enforce.py collects\nbuild context} C --> D[Compute artifact SHA-256] C --> E[Identify registry source] C --> F[Locate SBOM if present] D & E & F --> G[Payload sent to\nNodeArmor Policy Engine] G --> H{Policy Engine\nEvaluates} H --> I[Provenance Check\nNIST 800-207 §2.1] H --> J[Signature Verification\nNIST 800-207 §2.3] H --> K[SBOM Analysis\nEO 14028 §4e] H --> L[CVE Risk Scoring] H --> M[NIST 800-207\nPillar Alignment] I & J & K & L & M --> N{Decision} N -->|All clear| O([✓ PASS — Build authorized\npipeline continues]) N -->|Violation detected| P([✗ BLOCK — Hard stop\npipeline exits 1]) style O fill:#166534,color:#fff,stroke:#16a34a style P fill:#991b1b,color:#fff,stroke:#dc2626 style G fill:#1e1b4b,color:#fff,stroke:#6366f1 style H fill:#1e1b4b,color:#fff,stroke:#6366f1 ``` ## 架构 ``` graph LR subgraph PUBLIC["🔓 Public — This Repository"] direction TB EP["enforce.py\nThin client shell\nFully auditable"] AP["auth.py\nAPI key management"] CF[".nodearmor/config.yaml\nPolicy configuration"] GH[".github/workflows/\nCI/CD integration"] end subgraph ENGINE["🔒 Private — Policy Engine (Managed Service)"] direction TB PE["Policy Engine\nNIST 800-207 evaluation"] SA["SBOM Analyzer\nCycloneDX + SPDX"] SV["Signature Verifier\nFederal baseline registry"] DL["Deception Layer\nGhost build / honeypot"] end PUBLIC -->|"HTTPS + X-NodeArmor-Key\nPackage · Registry · SHA-256 · SBOM"| ENGINE ENGINE -->|"PASS / BLOCK\nFindings · Risk score"| PUBLIC style PUBLIC fill:#0f172a,color:#94a3b8,stroke:#334155 style ENGINE fill:#1e1b4b,color:#a5b4fc,stroke:#6366f1 ``` **为何这样设计？** - **客户端（此仓库）** 完全可审计。任何人都可以阅读 `enforce.py` 的每一行，确切验证收集和发送的数据。没有隐藏的行为。 - **引擎（私有）** 包含策略逻辑、威胁情报和欺骗层。由于它永远不会在对手的基础设施上运行，因此无法被逆向工程。 - 这与 Semgrep、Snyk 和 HashiCorp Sentinel 使用的模型相同——联邦社区信任它。 ## 快速开始 ### 前置条件 - Python 3.10 或更高版本 - NodeArmor API 密钥（`NODEARMOR_API_KEY`） - 无其他依赖——纯 Python 标准库 ### 1. 克隆仓库 ``` git clone https://github.com/saisravan909/nodearmor.git cd nodearmor ``` ### 2. 设置 API 密钥 ``` # 推荐：environment variable（切勿提交 API 密钥） export NODEARMOR_API_KEY=na_your_key_here # 或保存到 config（添加至 .gitignore） python3 auth.py set na_your_key_here ``` ### 3. 运行门禁 ``` python3 enforce.py \ --package lodash@4.17.21 \ --registry https://registry.npmjs.org ``` **预期输出（PASS）：** ``` ╔══════════════════════════════════════════════════════╗ ║ N O D E A R M O R · GATE v1.0 ║ ║ NIST SP 800-207 · EO 14028 · Zero Trust ║ ╚══════════════════════════════════════════════════════╝ Package : lodash@4.17.21 Registry : https://registry.npmjs.org Time : 2026-04-04T14:22:31+00:00 Submitting to NodeArmor Policy Engine ... [✓] Provenance verified — authorized registry confirmed [✓] Signature matches federal baseline [✓] SBOM analyzed — 1 component, no threats detected [✓] NIST 800-207 alignment verified ╔══════════════════════════════════════════════════════╗ ║ ✓ GATE PASSED — Build authorized to proceed ║ ╚══════════════════════════════════════════════════════╝ ``` **预期输出（BLOCK）：** ``` ╔══════════════════════════════════════════════════════╗ ║ N O D E A R M O R · GATE v1.0 ║ ║ NIST SP 800-207 · EO 14028 · Zero Trust ║ ╚══════════════════════════════════════════════════════╝ Package : compromised-pkg@3.3.6 Registry : https://malicious-registry.example.com Time : 2026-04-04T14:22:31+00:00 Submitting to NodeArmor Policy Engine ... [✗] Unauthorized registry detected 'malicious-registry.example.com' is not in the federal approved list [✗] Signature mismatch — artifact may be tampered SHA-256 does not match federal baseline. Possible supply chain compromise. [✗] SBOM absent — dependency provenance unknown ╔══════════════════════════════════════════════════════╗ ║ ✗ GATE BLOCKED — Hard stop. Build rejected. ║ ╚══════════════════════════════════════════════════════╝ ``` ### 4. 运行工件完整性检查 ``` python3 enforce.py \ --package myapp@2.1.0 \ --registry https://pypi.org \ --artifact dist/myapp-2.1.0.tar.gz ``` ## GitHub Actions 集成 在 60 秒内将 NodeArmor 添加到任何 GitHub Actions 工作流： ``` # .github/workflows/nodearmor-gate.yml name: NodeArmor Supply Chain Gate on: push: branches: [main] pull_request: branches: [main] jobs: nodearmor-gate: name: Zero Trust Enforcement Gate runs-on: ubuntu-latest permissions: pull-requests: write contents: read steps: - name: Checkout uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: "3.12" - name: Run NodeArmor Gate env: NODEARMOR_API_KEY: ${{ secrets.NODEARMOR_API_KEY }} run: | python3 enforce.py \ --package "${{ github.repository }}@${{ github.sha }}" \ --registry "https://github.com/${{ github.repository }}" - name: BLOCK — Hard Stop if: failure() run: | echo "::error title=NodeArmor Gate Blocked::Supply chain violation detected." exit 1 ``` 将您的 API 密钥添加到 **Settings → Secrets → Actions**，命名为 `NODEARMOR_API_KEY`。 ## 配置 ``` # .nodearmor/config.yaml # API key（更推荐使用 NODEARMOR_API_KEY envvar，而不是存储在此处） # api_key: "na_your_key_here" # Policy Engine endpoint api_url: "https://node-armor-enforcement.replit.app/api/evaluate" # 严重性阈值 — 在此级别及以上进行阻止 # 选项：LOW | MEDIUM | HIGH | CRITICAL severity_threshold: "HIGH" # 授权的 package registries — provenance 数据来源 authorized_registries: - "registry.npmjs.org" - "pypi.org" - "files.pythonhosted.org" - "registry.federal.gov" - "ghcr.io" # SBOM format（构建工具链预期格式） # 选项：cyclonedx | spdx | auto sbom_format: "auto" # Webhook 通知（Slack、Teams、PagerDuty 等，用于 BLOCK 事件） notify_webhook: "" ``` ### 环境变量 | 变量 | 必填 | 描述 | |----------|----------|-------------| | `NODEARMOR_API_KEY` | **是** | 您的 NodeArmor API 密钥（`na_...`）| | `NODEARMOR_API_URL` | 否 | 覆盖策略引擎端点 | ## 检查内容 ``` mindmap root((NodeArmor\nPolicy Engine)) Provenance Registry authorization Source-of-truth validation NIST 800-207 §2.1 Signature Integrity SHA-256 artifact hash Federal baseline comparison Tamper detection NIST 800-207 §2.3 SBOM Analysis CycloneDX parsing SPDX parsing Dependency graph risk EO 14028 §4e compliance CVE Risk Scoring Known vulnerability feed Severity classification Threshold enforcement NIST 800-207 All six Zero Trust pillars Continuous audit logging Policy alignment score Deception Layer Adversarial probe detection Ghost build activation TTP capture ``` ## NIST SP 800-207 对齐 每个执行决策都映射到零信任架构标准： | 支柱 | NIST 控制项 | NodeArmor 检查 | |--------|-------------|-----------------| | **身份** | §2.1 — 资源授权 | 注册表来源验证 | | **设备** | §2.2 — 设备完整性 | 构建环境态势 | | **网络** | §2.3 — 传输中数据完整性 | 工件签名验证 | | **应用程序工作负载** | §2.4 — 最小权限访问 | 依赖范围执行 | | **数据** | §2.5 — 数据分类 | SBOM 完整性和准确性 | | **可见性** | §2.6 — 持续监控 | 每次评估的不可变审计日志 | 同时符合： - **EO 14028** §4(e) — 所有联邦软件的 SBOM 要求 - **SSDF (SP 800-218)** — 安全软件开发框架 - **CMMC 2.0** — 第 2 级和第 3 级供应链控制 ## 行业用例

01 — 联邦机构：软件供应链安全

联邦机构面临 FISMA、FedRAMP 和 EO 14028 要求。NodeArmor 在每次构建时强制执行 SBOM 收集、签名验证和授权注册表检查——自动满足供应链安全要求，无需额外工具或采购。 [详细说明 →](use-cases/01-federal-agency-supply-chain/)

02 — 国防承包商：CMMC 对齐

CMMC 2.0 第 2 级和第 3 级要求有文档化的供应链风险管理。NodeArmor 为每次构建决策提供不可变的审计日志，满足 AC.2.007、CM.2.061 和 SI.1.210 控制项。 [详细说明 →](use-cases/02-defense-contractors/)

03 — 关键基础设施：ICS/OT 保护

工业控制系统需要确定性、低延迟的安全决策。NodeArmor 的二元 PASS/BLOCK 结果可与 OT 流水线集成，不会增加人机交互延迟。 [详细说明 →](use-cases/03-critical-infrastructure/)

04 — 红队 / 紫队：对抗性测试

NodeArmor 的欺骗层主动从红队演练中捕获 TTPs，生成真实威胁情报，而不仅仅是阻止攻击。 [详细说明 →](use-cases/04-red-team-purple-team/)

05 — 政府软件供应商：FedRAMP

向联邦机构销售软件的 ISV 需要展示供应链安全作为 FedRAMP 授权的一部分。NodeArmor 的审计日志和 NIST 800-207 对齐直接支持授权包。 [详细说明 →](use-cases/05-government-software-vendors/)

06 — 企业 CI/CD：DevSecOps 集成

NodeArmor 可嵌入任何 GitHub Actions、GitLab CI、Jenkins 或 CircleCI 流水线，无需重新配置现有工作流。一个文件、一个密钥、每次运行都强制执行。 [详细说明 →](use-cases/06-enterprise-cicd/)

07 — 医疗行业：HIPAA 供应链合规

医疗组织面临 OCR 指导，要求处理 PHI 的系统具备软件供应链安全。NodeArmor 的 SBOM 执行和依赖风险评分解决 HIPAA §164.308(a)(1) 安全管理要求。 [详细说明 →](use-cases/07-healthcare/)

08 — 金融服务：SOC 2 + PCI DSS

受 PCI DSS 4.0 和 SOC 2 Type II 审计的金融机构需要文档化的变更管理和软件完整性控制。NodeArmor 的不可变审计日志同时满足两者。 [详细说明 →](use-cases/08-financial-services-banking/)

## 信任模型：开放客户端 + 私有引擎 ``` sequenceDiagram participant DEV as Developer participant CLIENT as enforce.py (Public) participant ENGINE as Policy Engine (Private) participant LOG as Audit Log DEV->>CLIENT: Push code to pipeline CLIENT->>CLIENT: Collect build context Note over CLIENT: Package · Registry · SHA-256 · SBOM path CLIENT->>ENGINE: POST /api/evaluate (HTTPS + API key) ENGINE->>ENGINE: Provenance check ENGINE->>ENGINE: Signature verification ENGINE->>ENGINE: SBOM analysis ENGINE->>ENGINE: NIST 800-207 scoring ENGINE->>LOG: Immutable audit entry ENGINE->>CLIENT: Decision + findings alt PASS CLIENT->>DEV: Exit 0 — Build authorized else BLOCK CLIENT->>DEV: Exit 1 — Hard stop end ``` **发送到策略引擎的内容：** ``` { "package": "myapp@2.1.0", "registry": "https://registry.npmjs.org", "sha256": "a3f5d...", "client_version": "1.0.0", "timestamp": "2026-04-04T14:22:31Z" } ``` 除此之外没有了。没有源代码。没有密钥。没有仓库内容。您可以通过阅读 `enforce.py` 验证这一点——整个负载构建在第 101–109 行可见。 ## 性能 | 指标 | 人工安全审查 | 传统扫描器 | NodeArmor | |--------|:---------------------:|:------------------:|:---------:| | **决策延迟** | 24–72 小时 | 5–30 分钟 | **< 30 秒** | | **需要人工** | 是 | 是（审核）| **否** | | **SBOM 检查** | 手动 | 单独工具 | **集成** | | **审计跟踪** | 手动日志 | 不一致 | **不可变、自动** | | **误报覆盖** | 常见 | 常见 | **设计上不可能** | | **复杂威胁响应** | 仅警报 | 仅阻止 | **阻止 + 捕获 TTPs** | ## 常见问题

为何策略引擎是私有的？

原因与 Snyk 的漏洞数据库和 Semgrep 的规则引擎不开源相同。如果执行逻辑是公开的，复杂的对手可以离线测试其有效载荷，直到通过为止。客户端（此仓库）完全可审计——您可以验证发送到 API 的每个字节。处理它的引擎运行在您无法访问的环境中，这就是关键所在。

我可以在本地运行 NodeArmor 吗？

私有云部署适用于无法将数据发送到外部 API 的组织。在 `config.yaml` 中使用内部策略引擎 URL 覆盖端点。联系 nodearmor@saisravancherukuri.com。

什么数据发送到 API？

包名称、注册表 URL、工件 SHA-256 哈希（如果提供）和时间戳。没有源代码、没有密钥、没有仓库内容。参见 `enforce.py` 第 101–109 行的确切负载构建。

这适用于 npm、pip、Maven、Go 模块吗？

是的。NodeArmor 与语言无关。任何具有名称、版本和注册表 URL 的包都可以评估。SBOM 支持涵盖由任何工具链（Syft、cdxgen 等）生成的 CycloneDX 和 SPDX 格式。

如果策略引擎无法访问会怎样？

设计上，NodeArmor **失败关闭**——如果引擎在 15 秒内无法到达，门禁返回 `BLOCK`。连接失败不会导致未验证的构建继续。这是零信任要求：永不假设授权；始终验证。

生产使用有许可要求吗？

NodeArmor 采用 BSL 1.1 许可。评估和非生产使用免费。生产部署需要商业许可，将于 2028-01-01 转换为 Apache 2.0。联系 nodearmor@saisravancherukuri.com。

## 仓库结构 ``` nodearmor/ ├── enforce.py # Enforcement gate client — the entry point ├── auth.py # API key management utility ├── .nodearmor/ │ └── config.yaml # Policy configuration schema ├── .github/ │ └── workflows/ │ └── nodearmor-gate.yml # Drop-in GitHub Actions workflow ├── use-cases/ │ ├── 01-federal-agency-supply-chain/ │ ├── 02-defense-contractors/ │ ├── 03-critical-infrastructure/ │ ├── 04-red-team-purple-team/ │ ├── 05-government-software-vendors/ │ ├── 06-enterprise-cicd/ │ ├── 07-healthcare/ │ └── 08-financial-services-banking/ ├── LICENSE.md # Business Source License 1.1 ├── SECURITY.md # Vulnerability reporting policy └── CONTRIBUTING.md # Contribution guidelines ``` ## 安全 发现客户端中的漏洞？请参阅 [SECURITY.md](SECURITY.md)。 NodeArmor 遵循负责任的披露原则。我们将在 72 小时内响应，并在公开公告前协调披露。

标签：Binary Analysis, CycloneDX, EO 14028, NIST SP 800-207, Provenance, Python, SBOM, SLSA, SPDX, Zero Trust, 二进制审计, 代码签名, 供应链完整性, 安全策略, 安全门禁, 提示词设计, 无后门, 硬件无关, 策略引擎, 网络安全挑战, 联邦政府安全, 自动化攻击, 跌倒检测, 软件供应链安全, 软件物料清单, 远程方法调用, 逆向工具