cybermatrix - An agentic AI-powered cybersecurity framework that

项目说明

CYBERMATRIX

> Agentic AI-Powered Cybersecurity Swiss Army Knife.

![Tests]()
![Python]()
![Co]()

CYBERMATRIX is a modular pentesting framework that chains network, web,
authentication, OSINT, and modules together under an LLM-driven
"AI Brain" that decides the next step in real time. Use it for authorized
security testing, CTFs, and learning only — see SECURITY.md for the legal
disclaimer.

Installation

Optional dependency groups live in pyproject.toml:

| extras | adds |
|----------|-------------------------------------------------------------------|
| network| paramiko, cryptography, beautifulsoup4[lxml] — SSH/FTP brute force|
| packet | scapy — traffic capture and ARP analysis |
| ui | textual, pyfiglet, colorama — dashboard and banner |
| dev | pytest, mypy, ruff, bandit, detect-secrets, etc. |

Set your LLM API key via env var (recommended):

Or edit config.yaml and set the api_key field — but ne a
real key to control. Use the env var.

Usage

Quick launcher (recommended)

For the 3 most common combos, use the bundled launcher — it sets env vars,
swaps LLM backend, and kills stale procs in one step. Same surface on bash
and bare Windows cmd:

make aliases work the same way on machines with GNU make installed:
make scan auto, make scan nvidia (with TARGET= o).

| | Purpose |
|--------------------------------|-----------------------------------------------------------------------------------------|
| CYBERMATRIX_ALLOW_LOOPBACK=1 | Permit scanning of 127.0.0.1, localhost, RFC1918, and link-local targets. Required for any local-target scan. |
| CYBERMATRIX_AUTO_CONFIRM=1 | Skip the interactive "yes" prompt that asks you to confirm legal authorization. Required for non-interactive / test runs. |
| CYBERMATRIX_LLM_TIMEOUT=<int>| O LLM request timeout in seconds (default 30). Increase for slow pro. |
| CYBERMATRIX_MODEL=<name> | Select the LLM model at runtime — o whatever is in config.yaml. Useful when one config supports multiple pro. |
| CYBERMATRIX_SCAN_PORT=<int> | Restrict network scan to one port. Used internally when --port is passed; rarely set by hand. |
| CYBERMATRIX_API_KEY=<key> | LLM provider API key. Recommended o config.yaml. |
| CYBERMATRIX_DNS_PIN_TTL=<sec> | Maximum window (seconds, float) between DNS rebinding detection checks for a single hostname. Default 5. Lower = stricter (catches rebinding flips faster, more getaddrinfo syscalls). Higher = faster scans, larger attack window. Set 0 to disable caching and re-resolve on every request. |

Third-party services disclosure

The optional OSINT module (-m osint) sends resol IP addresses to
ipapi.co for geolocation/ASN lookups, and probes public
profile URLs (github.com, twitter.com, …) for username enumeration. If that is
unacceptable for your engagement, skip the osint module — no other module
contacts third parties.

Launcher security posture

Launchers (run.sh, run.cmd, scripts/cybermatrix.*) ship safe defaults:
loopback targets are refused, the legal-authorization prompt always shows, and
TLS stays on. Non-interacti workflows must opt in per run:

Fully offline mode (USB AI)

CyberMatrix can plan + dri with zero external API calls by
pairing it with a locally-running USB AI FastAPI server
(llama-cpp-python).

1. Run USB AI on the host where it lives. CyberMatrix defaults to
— set base_url to match wherever
USB AI is bound.
2. Make sure USB AI exposes POST /chat/completions with an
OpenAI-compatible request/response shape. If it doesn't yet,
add that adapter on the USB AI side first — CyberMatrix sends
standard chat-completions JSON via the OpenAI SDK.
3. Edit config.yaml:

4. Run as normal. AIBrain._plan_attack, _ai_summary, and the rest
of the AI-orchestrated paths now route through USB AI without
touching the internet:

The same --auto flag that drives the AI brain for cloud pro
also drives it for USB AI — same scan, same findings, same reports.

Supported LLM pro (any of these work the same way):

| provider | cost | notes |
|-------------|--------------|-------|
| ollama | free, local | default; local llama-cpp server |
| nvidia | free tier | default key in this repo's example; rotate before sharing |
| openrouter| paid | base_url: |
| openai | paid | needs sk-... key |
| anthropic | paid | needs sk-ant-... key |
| usb_ai | free, local | fully offline mode — see below |

CLI Flags Reference

| Flag | Description |
|---------------------|-----------------------------------------------------------------------------------|
| -t / --target | Target URL, IP, or domain (required unless --resume) |
| -m / --modules | Space-separated module names (default: all suitable for target type) |
| --auto | Let the AI Brain autonomously order modules |
| --dashboard | Open the real-time TUI dashboard (--threads also recommended) |
| --all | Enable e including brute force and aggressive rate limits |
| --threads N | Parallel worker threads for module execution (default 3) |
| --module-timeout N| Per-module timeout in seconds (default 60) |
| --no-banner | Suppress the ASCII banner |
| --dry-run | config + target, then exit without scanning |
| --list-modules | Print module table and exit |
| --resume SID | Resume a saved scan session |
| --insecure | Disable SSL (not recommended) |
| --output FORMAT | Report format: html / json / md / all (default all) |
| --port N | Restrict network scan to a single port |
| --no-ansi | Disable colors for piping to files |

Run py cybermatrix.py --help for the full list.

Modules

| Key | Name | What it does |
|-------------|-------------|------------------------------------------------------------|
| recon | RECON | WHOIS, DNS, subdomains, tech fingerprinting, robots/sitemap |
| network | NETWORK | Port scan, raw sockets, service detection, OS fingerprint |
| traffic | TRAFFIC | Packet capture, MITM detection, ARP |
| brute | BRUTE | SSH / FTP / HTTP credential testing (disabled by default) |
| auth | AUTH | JWT, cookies, OAuth, session entropy |
| vuln | VULN | C, SSL audit, CMS checks, open redirects |
| crypto | CRYPTO | Hash detection, entropy analysis, steganography hints |
| exploit | EXPLOIT | AI-powered exploit chain suggestions |
| osint | OSINT | Username enum, breach check, reverse IP, ASN |
| wireless | WIRELESS | Wi-Fi scanner, rogue-AP, WPA capture (Linux/mac only) |

For module details and reference, see docs/MANUAL.md.

Output Artifacts

After each scan, three files land in reports/:

Filenames use the YYYY-MM-DD_HH-MM-SS format. Audit logs land in
sessions/<session-id>_audit.jsonl and logs/audit.log.

Architecture

For an o of the runtime data flow (CLI -> AIBrain -> modules ->
E -> Reporter) see docs/ARCHITECTURE.md.

API Reference

The full auto-generated class / method / function reference is
generated from docstrings . Build with:

Source: docs/api-src/. Preview rendered docs:
docs/api-reference.md.

Software Bill of Materials

A CycloneDX SBOM is generated alongside each release for downstream
scanning. See docs/sbom-policy.md.

Legal

Only scan targets you ha written permission to test. Unauthorized
scanning is illegal in most jurisdictions. See SECURITY.md.

项目信息

开发语言：Python

Star 数：2

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕An agentic AI-powered cybersecurity framework that autonomously chains offensive and defensive security modules to scan, analyze, and report vulnerabilities.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。