dariomory/matadore

# matadore   **AI-powered attack surface mapping for red teams.** Matadore thinks like an attacker. Point it at your infrastructure - domains, IPs, repos, cloud configs, registries - and it maps your exposed surface, chains vulnerabilities into realistic kill chains, and tells you exactly how an adversary would get in. Built for red teams and security engineers who want adversarial reasoning, not just a checklist.  * **GitHub:** https://github.com/dariomory/matadore/ * **PyPI package:** https://pypi.org/project/matadore/ * **Created by:** **[Dario Mory](https://mory.dev)** · [GitHub](https://github.com/dariomory) · [PyPI](https://pypi.org/user/dariomory/) ``` pip install matadore ``` ## 责任使用 **免责声明：** Matadore **不** 验证你是否被允许扫描任何目标。仅将其用于你**拥有**或已获得**明确书面授权**测试的系统与数据（例如已签署的工作范围、渗透测试授权书或内部红队章程）。未经授权访问计算机系统和网络在许多司法管辖区属于违法行为，并可能导致民事责任。**你仅对该软件的使用以及遵守适用法律和组织政策负责。** ## 问题 安全扫描器给你一份列表。Matadore 给你一个故事。 | 无 Matadore | 有 Matadore | |---|---| | CVE 列表 | 链式攻击路径 | | 扫描器输出 | 对手推理 | | 通用风险评分 | “他们是如何进入的” | | 手动红队准备 | AI 辅助威胁建模 | | 一次性报告 | 持续差异扫描 | | 独立工具 | 原生 CI/CD 集成 | ## 快速开始 Matadore 使用 [LiteLLM](https://github.com/BerriAI/litellm) 进行推理——带上你自己的密钥使用任何支持的提供方。你的数据永远不会触达 Matadore 的服务器。 ``` from matadore import Matadore # OpenAI m = Matadore( model="gpt-4o", api_key="sk-...", # or set OPENAI_API_KEY in env ) # Anthropic m = Matadore( model="claude-opus-4-5", api_key="sk-ant-...", # or set ANTHROPIC_API_KEY in env ) # 本地模型 - 零数据外流，无需 API 密钥 m = Matadore( model="ollama/llama3", ) report = m.engage("mydomain.com") print(report.summary()) ``` 请参阅 [责任使用](#responsible-use)。 ## 支持的模型 任何 [LiteLLM](https://docs.litellm.ai/docs/providers) 识别的模型字符串均可开箱即用。提供方会根据前缀自动推断。 | 提供方 | 示例模型字符串 | API 密钥环境变量 | |---|---|---| | OpenAI | `gpt-4o`, `gpt-4o-mini` | `OPENAI_API_KEY` | | Anthropic | `claude-opus-4-5`, `claude-sonnet-4-5` | `ANTHROPIC_API_KEY` | | Google Gemini | `gemini/gemini-2.0-flash` | `GEMINI_API_KEY` | | Mistral | `mistral/mistral-large-latest` | `MISTRAL_API_KEY` | | AWS Bedrock | `bedrock/anthropic.claude-3-5-sonnet` | AWS 凭证 | | Azure OpenAI | `azure/gpt-4o` + `base_url=` | `AZURE_API_KEY` | | Ollama（本地） | `ollama/llama3`, `ollama/mistral` | *(无)* | 将密钥以 `api_key=` 形式传递或导出环境变量——Matadore 从不要求你代为管理凭证。 ## 攻击面输入 ``` # 域名与子域名 m.engage("mydomain.com", type="domain") # 网络范围 m.engage("192.168.1.0/24", type="network") # 源代码与提交历史 m.engage("myorg/myrepo", type="repo") # 整个 GitHub 组织 - 公共仓库，提交历史中的密钥，暴露的密钥 m.engage("myorg", type="github_org") # 云配置漂移与过度授权 m.engage("my-aws-account", type="cloud", provider="aws") m.engage("my-gcp-project", type="cloud", provider="gcp") # Docker 注册表 - 包含凭据的镜像 m.engage("myorg/myimage", type="docker_registry") ``` ## 核心用法 ### 先进行干运行 在任何主动扫描之前，查看 Matadore 将触及的内容： ``` plan = m.engage("mydomain.com", dry_run=True) plan.show() # 输出： # [DOMAIN] 将解析并枚举：mydomain.com + 14 个发现的子域名 # [NETWORK] 将探测：192.168.1.12、192.168.1.45（跳过 .0/广播） # [REPO] 将克隆（只读）：myorg/myrepo @ HEAD # [CLOUD] 将调用：ec2:DescribeInstances、s3:ListBuckets（只读 IAM） # # 范围内的总资产：31 # 预计耗时：约 4 分钟（主动模式） # 运行 m.engage("mydomain.com") 以继续。 ``` `dry_run=True` 可防止意外自我拒绝服务（DoS）、IDS 触发或扫描超出授权范围的资产。 ### 映射攻击面 ``` report = m.engage("mydomain.com") report.surface # all exposed assets report.vulnerabilities # findings ranked by exploitability report.entry_points() # most likely initial access vectors report.shadow_it() # assets you didn't know were public ``` `snapshot()` 视图通常是最有价值的输出——暴露团队未察觉的开发服务器、暂存环境和遗忘的 S3 存储桶。 ### 将漏洞链成攻击路径 ``` # 完整对抗杀伤链 report.attack_paths() # 首先受到攻击的是什么，以及原因 report.what_would_they_hit_first() ``` 每个发现都包含一个 `evidence` 字段——支持该主张的确切端口响应、代码行或 API 响应。Matadore 从不断言无法引用的路径。 ``` for path in report.attack_paths(): print(path.narrative) # human-readable kill chain print(path.evidence) # source data: line of code, packet capture, API response print(path.mitre_ttps) # mapped ATT&CK techniques ``` ### 实时流模式 ``` # 在侦察运行时实时流入的发现结果 for event in m.engage("mydomain.com", stream=True): print(f"[{event.level}] {event.description}") # [CRITICAL] Exposed .env file at https://api.mydomain.com/.env # [HIGH] SSH key found in commit a3f91c (myorg/infra-repo) # [INFO] Subdomain discovered: staging.mydomain.com # Stop if a sensitive asset appears if "prod-db" in event.asset: event.halt() ``` ### 生成红队简报 ``` brief = report.brief() brief.to_markdown() brief.to_pdf() ``` 示例输出： ### 差异模式——追踪变更 ``` report = m.engage("mydomain.com").diff(since="last_week") report = m.engage("mydomain.com").diff(since="2026-04-01") report = m.engage("mydomain.com").diff(baseline=previous_report) ``` Matadore 在本地（SQLite）缓存参与状态，因此重复扫描仅重新处理已变更的资产。大规模基础设施扫描不会从零开始。 ## CLI 红队生活在终端中。CLI 使用 [Rich](https://github.com/Textualize/rich) 提供彩色输出、实时进度条和交互式表格。 ``` # 完整参与 matadore engage mydomain.com # 干运行预览 matadore engage mydomain.com --dry-run # 实时流式发现结果 matadore engage mydomain.com --stream # 与上次扫描的差异 matadore engage mydomain.com --diff # 导出报告 matadore engage mydomain.com --export sarif --out results.sarif matadore engage mydomain.com --export pdf --out brief.pdf ``` Web UI（如正在运行）是**只读管理仪表板**——用于与利益相关者共享发现。所有操作和扫描均存在于 SDK 和 CLI 中。 ## CI/CD 集成 ``` report = m.engage(os.environ["DEPLOY_DOMAIN"]) # 在新关键发现上使流水线失败 report.assert_no_new_criticals() # SARIF → GitHub Security 标签 report.export("sarif", path="matadore-results.sarif") # JSON-ASFF → AWS Security Hub / Jira / Splunk report.export("asff", path="matadore-results.asff.json") ``` **GitHub Actions 示例：** ``` - name: Matadore attack surface scan env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} # or ANTHROPIC_API_KEY, etc. run: | python -c " from matadore import Matadore m = Matadore(model='gpt-4o') report = m.engage('${{ vars.DEPLOY_DOMAIN }}') report.export('sarif', path='results.sarif') report.assert_no_new_criticals() " - name: Upload to GitHub Security uses: github/codeql-action/upload-sarif@v3 with: sarif_file: results.sarif ``` ## 报告对象 ``` report.surface # all exposed assets report.vulnerabilities # findings ranked by exploitability, with evidence report.attack_paths() # chained exploit sequences report.entry_points() # most likely initial access vectors report.shadow_it() # assets not in your known inventory report.what_would_they_hit_first() # adversary priority model report.brief() # narrative red team report report.mitre_mapping() # findings mapped to ATT&CK tactics/techniques report.remediation_plan() # prioritised fix list with effort estimates report.delta(previous_report) # regression detection across engagements report.audit_log() # tamper-evident chain of custody report.assert_no_new_criticals() # CI/CD gate report.export("sarif") # SARIF - GitHub Advanced Security report.export("asff") # JSON-ASFF - AWS Security Hub, Splunk, Jira report.export("markdown") # red team brief report.export("pdf") # stakeholder report ``` 每个 `Vulnerability` 和 `AttackPath` 对象都是一个带有强制 `evidence` 字段的类型化 Pydantic 模型。AI 在没有可验证的源引用时无法断言一个发现。 ## 插件架构 Matadore 将编排与扫描分离： - **核心** = 大脑 —— AI 推理、路径链、报告生成 - **插件** = 眼睛 —— 封装现有最佳工具 ``` # 内置插件 from matadore.plugins import Nmap, Nuclei, Trivy, GitLeaks, ScoutSuite m = Matadore( model="gpt-4o", plugins=[Nmap(), Nuclei(), Trivy(), GitLeaks()], ) ``` 自行编写： ``` from matadore.plugins import BasePlugin class MyScanner(BasePlugin): def run(self, target: str) -> list[RawFinding]: ... ``` 这意味着 Matadore 不会重新实现 nmap、nuclei 和 trivy 已擅长的功能——它是在其输出之上进行推理。 ## 扫描模式 ``` # 被动 - 无主动探测，零噪声（CI 默认） m.engage("mydomain.com", mode="passive") # 主动 - 完整指纹识别与利用链（红队默认） m.engage("mydomain.com", mode="active") # 隐身 - 模拟正常流量模式，速率限制 m.engage("mydomain.com", mode="stealth") ``` 所有模式均包含自动速率限制与智能退避——Matadore 会针对 GitHub API、云端点和速率受限服务自动自我限速，以避免触发告警或耗尽 API 配额。 ## 审计追踪 参与式设计支持**审计日志**——记录扫描时间、内容和执行者，以便你符合自身治理要求（已记录的渗透测试、红队计划或内部策略）。Matadore 不会取代法律审查或客户授权流程。 ``` report.audit_log() # chain of custody for this engagement ``` ## 部署 Matadore 支持两种部署模式： | 模式 | 工作方式 | 适用场景 | |---|---|---| | **云提供方密钥** | 你提供 OpenAI / Anthropic / Gemini 密钥；推理直接使用该提供方 | 初创公司、小型红队、快速上手 | | **本地部署（Ollama）** | 在网络内运行本地模型；零数据外传 | 企业、合规行业、机密环境 | | **Azure / Bedrock** | 使用现有的云端 LLM 终端；数据保留在 VPC 内 | 已拥有云 LLM 合同的企业 | ``` # 本地 - 本地 Ollama 模型，数据不离开您的网络 docker run --rm \ -e MATADORE_MODEL=ollama/llama3 \ -e OLLAMA_BASE_URL=http://your-ollama-host:11434 \ -v $(pwd)/reports:/reports \ matadore/runner:latest \ engage mydomain.com --export sarif --out /reports/results.sarif ``` ## 技术设计 | 关注点 | 方法 | |---|---| | **LLM 推理** | [LiteLLM](https://github.com/BerriAI/litellm) —— 统一接口支持 OpenAI、Anthropic、Gemini、Bedrock、Ollama 等 | | **类型安全** | 所有 `Finding`、`AttackPath` 和 `Report` 对象均使用 Pydantic 模型 | | **并发** | `asyncio` 贯穿映射阶段——100 个 IP 并行扫描，而非顺序执行 | | **状态与缓存** | SQLite（本地）或 DuckDB（团队共享）避免重复扫描未变更资产 | | **速率限制** | 对 GitHub、AWS 和 GCP API 端点自动退避 | | **测试** | VCR.py 录制并回放网络交互——CI 运行永不消耗 API 信用 | | **证据要求** | 每个 `Finding` 必须包含强制 `evidence: Evidence` 字段——无不可验证的断言 | ### 领域模型  ## 路线图 - [ ] `type="sl_workspace"` —— 社交工程表面映射 - [ ] `type="email_domain"` —— 钓鱼与预设场景暴露 - [ ] Azure 提供方支持 - [ ] 攻击图可视化（使用 Cytoscape.js）在 Web 仪表板中 - [ ] VS Code 扩展 —— 开发过程中内联显示发现 - [ ] 团队模式 —— 共享组织状态与跨参与协作 - [ ] 参与模板（外部渗透测试、内部威胁、供应链） ## 开发 要设置本地开发环境： ``` # 克隆你的分叉 git clone git@github.com:your_username/matadore.git cd matadore # 以可编辑模式安装并启用实时更新 uv tool install --editable . ``` 这将全局安装 CLI，但支持实时更新——你对源代码的任何修改在运行 `matadore` 时会立即生效。 运行测试： ``` uv run pytest ``` 运行质量检查（格式化、Lint、类型检查、测试）： ``` just qa ``` ## 作者 matadore 由 Dario Mory 于 2026 年创建。 ## 许可证 MIT - 请参阅 [LICENSE](LICENSE)。

标签：AI安全, Chat Copilot, DLL 劫持, IP扫描, LiteLLM, LNA, PyPI安全工具, Python安全工具, TShark, 云资产清单, 云配置, 代码仓库, 域名枚举, 大语言模型, 威胁建模, 安全工程, 安全扫描, 对抗推理, 开源安全工具, 攻击路径, 攻击面映射, 数据展示, 时序注入, 杀伤链, 漏洞链, 红队, 计算机取证, 逆向工具, 逆向工程, 逆向工程平台