batu3384/ironsentinel

# IronSentinel

本地优先的 AppSec 指挥中心，用于扫描源代码树、验证运行时信任、审查发现并导出富含证据的报告。

`IronSentinel` 是主要产品，`ironsentinel` 是主要的二进制文件。 当你在交互式终端中运行 `ironsentinel` 时，它默认会打开主要的单控制台操作界面。该界面保持在一个连续的 `Launch -> Mission -> Debrief`（启动 -> 任务 -> 总结）流程中，通过侧边抽屉展示发现、运行时信任和运行证据，而不是在操作员面前频繁切换不同的顶级路由。该平台在本地保存项目历史，运行引导式的安全任务，将发现结果标准化为统一的模型，并无需托管控制平面即可导出可共享的报告。 ## 为什么选择 IronSentinel - 本地优先的安全工作流，数据存储在 `runtime/data/state.db` 下 - 全屏单控制台操作流程，涵盖启动、任务执行、总结和证据审查 - 内置启发式覆盖，并在可用时结合可信工具进行外部扫描器编排 - 具备证据感知的运行，包含 artifacts、执行日志、重试状态和可导出的报告 - 双语操作体验，支持 `English` 和 `Turkish` - 针对 `NO_COLOR`、非交互式输出和减少动态效果提供 shell 安全的降级方案 ## 产品界面 下面的截图展示了主要的单控制台工作流及其面向总结的证据抽屉。基于路由的兼容界面仍然存在以用于迁移，但它们已不再是需要首先学习的产品模型。 以下截图是通过核心扫描在本仓库的真实产品 UI 中生成的，因此发现队列特意展示了预置的测试 fixtures。 | 指挥中心 | 引导式扫描审查 | | --- | --- | |  |  | | 运行账本 | 分析师队列 | |  |  | ## 核心工作流 1. 准备可信的 runtime。 ironsentinel setup --target auto --coverage premium ironsentinel runtime doctor --mode safe --require-integrity 2. 打开单控制台操作界面。 ironsentinel --lang en 3. 从单控制台的启动阶段或直接从 CLI 启动扫描。 ironsentinel scan /absolute/path --coverage core ironsentinel scan /absolute/path --coverage premium ironsentinel scan /absolute/path --coverage full 4. 审查发现、比较运行并导出报告。 ironsentinel findings --run ironsentinel runs show ironsentinel export --format html --output runtime/output/report.html ironsentinel runs gate --vex-file ./triage.openvex.json ## 经过身份验证的 DAST 配置 可重用的 DAST 身份验证配置允许你将目标选择与凭据配置分开。 直接从 CLI 生成规范模板： ``` ironsentinel dast auth-template ironsentinel dast auth-template form ``` 示例 `dast-auth.json`： ``` { "profiles": [ { "name": "staging-bearer", "type": "bearer", "secretEnv": "STAGING_API_TOKEN", "sessionCheckUrl": "https://api.example.test/me", "sessionCheckPattern": "200 OK" } ] } ``` 将配置文件与明确的目标-配置绑定结合使用： ``` ironsentinel dast plan \ --target api=https://api.example.test \ --target-auth api=staging-bearer \ --dast-auth-file ./dast-auth.json ``` 相同的标志在 `scan` 上也适用，因此经过身份验证的 API 验证可以流经正常的审查、运行和导出 pipeline，而无需更改其余的命令界面。 ## 覆盖模型 IronSentinel 默认启用启发式检测，当 `PATH` 上或通过托管的 runtime 包提供可用工具时，会扩展到更深的覆盖范围。 | 通道 | 内置覆盖 | 外部适配器 | | --- | --- | --- | | 攻击面与仓库暴露 | 技术栈检测、攻击面清单、脚本审计、runtime 配置审计 | semgrep, staticcheck | | 代码与机密 | 机密启发式检测、证据捕获、执行日志 | gitleaks, govulncheck, knip, vulture, codeql | | 依赖与供应链 | 依赖混淆检查、标准化供应链发现 | syft, trivy, osv-scanner, grype | | 基础设施与配置 | runtime 和 IaC 启发式检测 | checkov | | 恶意软件与可疑 payload | 恶意软件签名、EICAR 验证、二进制熵检查 | clamscan | | 主动验证 | 启动规划和信任门控 | nuclei, OWASP ZAP Automation Framework | 默认扫描使用 `premium` 覆盖。要在全新的机器上进行可移植的仅内置检查，请使用 `--coverage core`。 ## 环境优先级 IronSentinel 使用 `IRONSENTINEL_*` 产品命名空间。 - 首选：`IRONSENTINEL_*` - 迁移期间的兼容性：`APPSEC_*` - 优先级：设置多个别名时，规范的 `IRONSENTINEL_*` 值优先 示例： ``` IRONSENTINEL_LANG=tr IRONSENTINEL_TOOLS_DIR=/opt/ironsentinel/tools IRONSENTINEL_CONTAINER_IMAGE=ghcr.io/batu3384/ironsentinel-scanner-bundle:latest ``` ## 报告与证据 每次扫描都可以持久化以下内容： - 带有严重程度、分类状态和审查元数据的标准化发现 - 包含命令、工作目录、环境白名单和退出码的模块清单 - 包含重试、超时和失败分类的执行日志 - 用于启发式检测的本地证据文件 - 当外部工具发出结构化结果时的原始扫描器输出 导出格式： - `HTML`，用于人类可读的审查 - `SARIF`，用于代码扫描和 CI 集成 - `CSV`，用于操作交接和电子表格工作流 - `OpenVEX`，用于包级别的漏洞状态交换 - `SBOM attestation`，用于签名或可审计的 SBOM 来源交接 示例： ``` ironsentinel export --format html --output runtime/output/report.html ironsentinel export --format sarif --baseline ironsentinel export --format csv --output runtime/output/findings.csv ironsentinel export --format openvex --vex-file ./triage.openvex.json ironsentinel export --format sbom-attestation > runtime/output/sbom-attestation.json ironsentinel runs verify-sbom-attestation --file runtime/output/sbom-attestation.json ironsentinel runs policy --policy premium-default --vex-file ./triage.openvex.json ``` ## GitHub 发布 IronSentinel 包含一个 GitHub 发布流程，用于将扫描证据推送到 GitHub 原生的安全界面。 ``` ironsentinel github export-custom-patterns ironsentinel github upload-sarif --repo owner/repo ironsentinel github submit-deps --repo owner/repo ironsentinel setup install-pre-push ``` `export-custom-patterns` 以兼容 GitHub 自定义模式的 JSON 清单格式输出 IronSentinel 的高置信度机密规则，以便操作员可以在 GitHub secret scanning 中映射相同的 token 覆盖范围。`upload-sarif` 将选定的运行导出为 SARIF 并将其上传到 GitHub code scanning。`submit-deps` 根据所选项目最近可用的清单构建依赖快照，并将其提交到 GitHub 依赖图。 `setup install-pre-push` 会安装一个本地 git hook，在每次 push 之前运行 `ironsentinel github push-protect`。该防护机制会扫描即将提交的 commit 集合，仅在发现高置信度的机密（如 GitHub personal access tokens 或 AWS 访问密钥）时阻止 push。 身份验证按以下顺序解析： - `GITHUB_TOKEN` - `GH_TOKEN` - `gh auth token` 这两个命令在可用时会从项目工作区解析仓库、ref 和 commit 元数据，并在需要覆盖推断的上下文时接受 `--repo`、`--ref`、`--sha` 以及特定于命令的选择器（如 `--baseline` 或 `--run`）。 ## 修复活动 活动会在将选定的发现发布到 GitHub Issues 之前，将它们分组到本地修复工作项中。在你明确发布之前，该工作流始终保持本地优先。 ``` ironsentinel campaigns create --project --run --finding ironsentinel campaigns list --project ironsentinel campaigns show ironsentinel campaigns publish-github --repo owner/repo ``` 全屏指挥中心在运行和发现详情面板中展示活动提示，以便操作员可以在不离开现有工作流的情况下，从分类直接跳转到活动创建。 ## 命令映射 | 任务 | 命令 | | --- | --- | | 打开全屏指挥中心 | `ironsentinel` | | 打开静态安全态势概览 | `ironsentinel overview` | | 运行引导式扫描任务 | `ironsentinel scan /absolute/path --coverage premium` | | 注册当前项目 | `ironsentinel init` | | 选择一个文件夹并开始扫描 | `ironsentinel scan --picker` | | 检查发现 | `ironsentinel findings --run ` | | 以交互方式审查单个发现 | `ironsentinel review --run ` | | 检查最近的运行 | `ironsentinel runs list` / `ironsentinel runs show ` | | 监视队列或特定运行 | `ironsentinel runs watch ` | | 将 OpenVEX 应用于门控和策略 | `ironsentinel runs gate --vex-file triage.openvex.json` / `ironsentinel runs policy --vex-file triage.openvex.json` | | 验证导出的 SBOM 来源 | `ironsentinel runs verify-sbom-attestation --file sbom-attestation.json` | | 管理修复活动 | `ironsentinel campaigns list|show|create|add-findings|publish-github` | | 验证 runtime 信任 | `ironsentinel runtime doctor --mode safe --require-integrity` | | 运行一次或持续运行队列 worker | `ironsentinel daemon --once` / `ironsentinel daemon` | | 导出报告和证据 | `ironsentinel export --format html|sarif|csv|openvex|sbom-attestation` | | 导出 GitHub secret scanning 模式 | `ironsentinel github export-custom-patterns` | | 将扫描证据发布到 GitHub | `ironsentinel github upload-sarif ` / `ironsentinel github submit-deps ` | | 安装本地 push 防护 | `ironsentinel setup install-pre-push` | 诸如 `console`、`open`、`pick` 和 `tui` 之类的兼容性命令仍可调用以进行迁移，但它们在主帮助信息中被隐藏，并引导操作员使用上述规范的单控制台工作流。 ## 无障碍与操作员降级方案 - `NO_COLOR=1` 将带样式的命令界面切换为 shell 安全的纯文本输出。 - `IRONSENTINEL_REDUCED_MOTION=1` 禁用非必要的 TUI 动画。 - `ironsentinel config language en|tr` 持久化保存首选的界面语言。 - `ironsentinel config ui-mode standard|plain|compact` 存储首选的 TUI 密度模式。 ## 从源码构建 ``` go mod tidy go build ./cmd/ironsentinel ``` 该项目目标为 Go `1.25.x`。 ## 本地质量门禁 运行与发布验证相同的本地质量门禁： ``` bash scripts/quality_local.sh ``` 这将执行： - `go test ./...` - `bash scripts/coverage_gate.sh` - `go vet ./...` - `staticcheck ./...` - `golangci-lint run --config .golangci.yml --concurrency 2 ./...` - 使用 `ironsentinel` 进行核心自扫描 Coverage artifacts 将写入： - `coverage/internal.out` - `coverage/internal-summary.txt` - `coverage/internal-packages.txt` 默认的最小内部覆盖率为 `45.0%`，可以使用 `COVERAGE_MIN` 覆盖。 ## 仓库布局 | 路径 | 用途 | | --- | --- | | `cmd/ironsentinel` | 主要产品二进制文件 | | `cmd/releasectl` | 发布验证和锁定补充工具 | | `internal/cli` | 指挥中心 UI、shell 安全界面和命令路由 | | `internal/agent` | 扫描器编排、runtime 探测和模块适配器 | | `internal/core` | 有状态工作流、项目组合数据、发现和 runtime doctor | | `internal/reports` | HTML、SARIF 和 CSV 导出路径 | | `internal/store` | 本地 SQLite 状态存储 | | `scripts` | 本地质量门禁、冒烟测试和发布自动化 | | `docs` | 现行的架构和发布规范文档 | | `docs/archive` | 历史审计、审查和修复快照 | ## 运行时与发布规范 - 支持矩阵和能力层级：[`docs/release-discipline.md`](docs/release-discipline.md) - 系统架构：[`docs/architecture.md`](docs/architecture.md) - setup 和 runtime 冒烟测试：`bash scripts/smoke_setup_doctor.sh` - shell 防护冒烟测试：`bash scripts/smoke_shell_guards.sh` - Windows shell 防护冒烟测试：`pwsh scripts/smoke_shell_guards.ps1` - 发布预检：`bash scripts/release_publish_preflight.sh --version vX.Y.Z --require-signing --require-tag` - 发布 artifact 预检：`bash scripts/release_artifact_preflight.sh --dir dist/vX.Y.Z --require-signing --require-external-attestation` ## 代表性命令 ``` go run ./cmd/ironsentinel go run ./cmd/ironsentinel overview go run ./cmd/ironsentinel scan /absolute/path --coverage core go run ./cmd/ironsentinel scan /absolute/path --coverage premium --fail-on-new high go run ./cmd/ironsentinel findings --severity high --limit 20 go run ./cmd/ironsentinel runs show go run ./cmd/ironsentinel runtime doctor --mode safe --require-integrity go run ./cmd/ironsentinel export --format html --output runtime/output/report.html go run ./cmd/ironsentinel github export-custom-patterns go run ./cmd/ironsentinel github upload-sarif --repo owner/repo go run ./cmd/ironsentinel github submit-deps --repo owner/repo go run ./cmd/ironsentinel setup install-pre-push go run ./cmd/releasectl verify --dir dist/ --lock scanner-bundle.lock.json --require-signature --require-attestation --require-external-attestation ``` 如需了解完整的命令界面，请运行： ``` ironsentinel --help ironsentinel --help ``` ## 许可证 IronSentinel 采用 [MIT 许可证](LICENSE)。

标签：CLI, EVTX分析, Go, Ruby工具, WiFi技术, 安全工具, 应用安全, 报告生成, 本地优先, 漏洞扫描