srini-cybersec/ir-commander

# IR-Commander [](https://github.com/srini-cybersec/ir-commander/actions/workflows/ci.yml) [](https://www.python.org/) [](LICENSE) [](#testing--quality) [](#security-considerations) IR-Commander 是一个**纯 Python、完全离线**的 DFIR 工具包。将它指向从可疑主机提取的取证文件目录 —— 包括认证日志、shell 历史记录、Web 访问日志、进程和网络快照 —— 它将重建统一的事件时间线，运行**包含 23 条规则的 MITRE ATT&CK 标记检测引擎**，对事件进行 0-100 的评分，并生成控制台 / JSON / CSV / SARIF / HTML 报告。它**不发起任何网络调用**，因此非常适合用于监管链证据处理和物理隔离的实验室环境。 ## 问题描述 当怀疑主机遭到入侵时，响应人员会收集各种日志和状态取证文件，然后面临一项缓慢且容易出错的手动关联工作：*那次 SSH 登录是否就是最终猜中密码的那次？攻击者是在清除历史记录之前还是之后建立的持久化？* IR-Commander 自动化了初步的分流处理：它将异构的取证文件标准化到同一条时间线上，应用经过实战检验且映射到 ATT&CK 的检测规则，并在几秒钟内为响应人员提供一份按优先级排序、关联了证据的发现列表 —— 且完全离线。 ## 功能 - **六大取证解析器，支持自动检测** —— Linux `auth.log`/`secure`，shell 历史记录（bash/zsh，带或不带时间戳），Apache/Nginx 访问日志，`ps aux`/`ps -ef`，`netstat`/`ss`，以及通用的 syslog 兜底解析。 - **超级时间线** —— 将所有事件合并到一个按时间顺序排列的视图中，包含计算出的时间窗口和按来源细分的详情。 - **涵盖 8 种 ATT&CK 战术的 23 条检测规则** —— 暴力破解、合法账户滥用、账户创建/持久化、反弹 shell、下载并执行、日志篡改、凭证转储、防御规避、Web 攻击（SQLi、LFI、Web shell、命令注入）、扫描器 UA，以及可疑的进程/网络状态。每项发现都包含技术 ID、置信度、修复建议和触发证据。 - **限制在 0-100 的风险评分**，具有按严重程度划分的上限和五级判定（`CRITICAL` / `HIGH_RISK` / `MODERATE` / `LOW_RISK` / `CLEAN`）。 - **五种报告格式** —— Rich 控制台、JSON、CSV、**SARIF 2.1.0**（GitHub 代码扫描）和独立的 HTML 仪表板。 - **对 CI 友好** —— `--fail-on`、`--min-severity`、`--exclude-rule`、环境变量配置，以及经过强化的非 root Docker 镜像。 ## 架构 ``` Artifacts Parser registry Normalized Detection (auth.log, history, -> (auto-detect / -> timeline -> engine -> Score + verdict access.log, ps, force parser) (Event[]) (23 rules) (0-100) netstat) | v console / JSON / CSV / SARIF 2.1.0 / HTML reports ``` 请参阅 [docs/architecture.md](docs/architecture.md) 了解完整的 pipeline 和 Mermaid 图。 ## 安装说明 ``` # 从源码构建（目前推荐） git clone https://github.com/srini-cybersec/ir-commander.git cd ir-commander python -m venv .venv && source .venv/bin/activate pip install -e . # 或者一次性引导开发环境并运行测试 ./scripts/setup.sh ``` 要求 Python 3.11+。运行时依赖项：`click`、`rich`、`jinja2`、`pyyaml`。 ## 用法 ``` # 对收集到的 artifacts 目录进行分流处理（生成丰富的控制台报告） ir-commander triage ./evidence/ --assume-year 2026 # 为 pipelines 输出机器可读的报告 ir-commander triage ./evidence/ -f json -o incident.json ir-commander triage ./evidence/ -f sarif -o incident.sarif ir-commander triage ./evidence/ -f html -o incident.html # 拦截 pipeline：如果达到任何 HIGH_RISK+ 判定，则以退出代码 2 退出 ir-commander triage ./evidence/ --fail-on HIGH # 仅构建按时间顺序排列的 super-timeline ir-commander timeline ./evidence/ --limit 50 # 检查 rule pack ir-commander rules ``` 立即针对内置的示例事件进行尝试： ``` ir-commander triage examples/sample_incident/ --assume-year 2026 --timeline 8 python examples/demo.py # programmatic API demo ``` ### 示例输出（示例事件） ``` ╭──────────────── IR-COMMANDER • Incident Triage Report ────────────────╮ │ Verdict: CRITICAL Risk Score: 100/100 │ ╰───────────────────────────────────────────────────────────────────────╯ Artifacts parsed 5 Events on timeline 27 Findings 18 Severity CRITICAL: 3 HIGH: 11 MEDIUM: 3 LOW: 1 CRITICAL IRC-AUTH-002 Successful SSH login after brute force T1110, T1078 CRITICAL IRC-AUTH-003 Privileged (UID 0) account created T1136, T1078 CRITICAL IRC-CMD-001 Reverse shell execution T1059 HIGH IRC-CMD-005 Persistence mechanism establishment T1053, T1098, T1543 ... ``` ## CLI 参考 | 命令 | 用途 | | --- | --- | | `triage PATHS...` | 解析、检测、评分并报告取证文件/目录 | | `timeline PATHS...` | 输出按时间顺序排列的超级时间线 | | `rules` | 列出内置检测规则（控制台或 `-f json`） | | `version` | 输出工具版本 | 核心 `triage` 选项：`-f/--format`、`-o/--output`、`--min-severity`、`--fail-on`、`--exclude-rule`（可重复）、`--force-parser`、`--assume-year`、`--utc-offset`、`--host`、`--brute-threshold`、`--timeline N`。 ### 配置 所有选项都可以通过带有 `IRC_` 前缀的环境变量进行设置，例如： ``` export IRC_MIN_SEVERITY=MEDIUM export IRC_FAIL_ON=HIGH export IRC_BRUTE_FORCE_THRESHOLD=8 export IRC_EXCLUDE_RULES="IRC-WEB-005,IRC-CMD-008" ``` 优先级：**CLI 参数 > 环境变量 > 默认值。** ## 检测规则 | `IRC-AUTH-001` | SSH 暴力破解尝试 | HIGH | T1110 | | `IRC-AUTH-002` | 暴力破解后 SSH 登录成功 | CRITICAL | T1110, T1078 | | `IRC-AUTH-003` | 创建了特权（UID 0）账户 | CRITICAL | T1136, T1078 | | `IRC-AUTH-004` | 创建了新账户或组 | MEDIUM | T1136 | | `IRC-AUTH-005` | Root 密码被修改 | HIGH | T1098 | | `IRC-AUTH-006` | 反复的 sudo 认证失败 | MEDIUM | T1548 | | `IRC-CMD-001` | 执行反弹 shell | CRITICAL | T1059 | | `IRC-CMD-002` | 下载并执行（curl/wget 管道传输至 shell） | HIGH | T1059, T1105 | | `IRC-CMD-003` | 日志或 shell 历史记录篡改 | HIGH | T1070 | | `IRC-CMD-004` | 凭证访问/转储 | HIGH | T1003, T1552 | | `IRC-CMD-005` | 建立持久化机制 | HIGH | T1053, T1098, T1543 | | `IRC-CMD-006` | 防御能力受损 | MEDIUM | T1562 | | `IRC-CMD-007` | 执行混淆（base64）的命令 | MEDIUM | T1027, T1059 | | `IRC-CMD-008` | 主机侦察/发现集群 | LOW | T1082, T1033 | | `IRC-WEB-001` | SQL 注入尝试 | HIGH | T1190 | | `IRC-WEB-002` | 路径遍历/LFI 尝试 | HIGH | T1190 | | `IRC-WEB-003` | Web shell 访问 | HIGH | T1505.003 | | `IRC-WEB-004` | 命令注入尝试 | HIGH | T1190 | | `IRC-WEB-005` | 安全扫描器 User-Agent | MEDIUM | T1595 | | `IRC-WEB-006` | 强制浏览/枚举 | MEDIUM | T1595 | | `IRC-PROC-001` | 可疑的正在运行的进程 | HIGH | T1059 | | `IRC-PROC-002` | 在临时目录中执行的进程 | MEDIUM | T1036 | | `IRC-NET-001` | 可疑端口上的监听器 | MEDIUM | T1571 | ## Docker ``` docker build -t ir-commander . docker run --rm --network=none -v "$PWD/evidence:/data:ro" \ ir-commander triage /data --assume-year 2026 -f sarif # 或者使用 docker-compose（只读、无网络、cap_drop ALL、非 root 用户） docker compose run --rm ir-commander triage /data -f json ``` 该镜像以非 root UID 10001 运行，具有只读文件系统且无网络访问权限。 ## 测试与质量 ``` pip install -e ".[dev]" pytest tests/ -v --cov=ir_commander --cov-report=term-missing black --check src/ tests/ --line-length 88 ruff check src/ tests/ mypy src/ --ignore-missing-imports --no-strict-optional bandit -r src/ -ll ``` - **82 个测试，96% 的代码覆盖率** - 经过 Black 格式化，符合 Ruff 规范，通过 Mypy 检查，在 `-ll` 级别下 Bandit 零发现 ## 安全注意事项 - **零网络调用。** 该包不导入任何网络模块；证据永远不会离开主机。可通过 `grep -rE 'requests|socket|urllib.request' src/` 进行验证。 - **防御性解析器。** 解析器有边界限制，从不 `eval` 或执行取证文件内容；格式错误或具有对抗性的行会被跳过，而不是被信任。 - **无静态机密。** 不读取或存储任何凭证或 API 密钥；测试夹具仅使用 RFC 5737 文档 IP 范围。 - **静态的、建议性的结果。** IR-Commander 执行初步分流。在得出结论或采取遏制行动之前，请务必根据主要证据验证发现。 - **仅限授权使用。** 仅限在您被授权调查的系统和数据上使用。 ## 贡献 欢迎贡献代码。 1. Fork 并创建一个功能分支。 2. 添加解析器（`ArtifactParser`）或规则（`Rule`/`PredicateRule`）以及相应的测试。 3. 确保通过 `black`、`ruff`、`mypy`、`bandit` 和 `pytest` 检查。 4. 提交 Pull Request，描述取证文件/技术并附上示例。 ## 许可证 [MIT](LICENSE) © 2026 srini-cybersec

标签：ATT&CK检测, Python, 库, 应急响应, 恶意代码分类, 数字取证, 无后门, 自动化脚本, 请求拦截, 逆向工具