# CyberStrikeAI
[δΈζ](README_CN.md) | [English](README.md)
CyberStrikeAI is an **AI-native penetration-testing copilot** built in Go. It combines hundreds of security tools, MCP-native orchestration, and an agent that reasons over findings so that a full engagement can be run from a single conversation.
π
- MCP stdio mode
- External MCP servers & attack-chain view
## Highlights
- π€ AI decision engine with OpenAI-compatible models (GPT, Claude, DeepSeek, etc.)
- π Native MCP implementation with HTTP/stdio transports and external MCP federation
- π§° 100+ prebuilt tool recipes + YAML-based extension system
- π Large-result pagination, compression, and searchable archives
- π Attack-chain graph, risk scoring, and step-by-step replay
- π Password-protected web UI, audit logs, and SQLite persistence
## Tool Overview
CyberStrikeAI ships with 100+ curated tools covering the whole kill chain:
- **Network Scanners** β nmap, masscan, rustscan, arp-scan, nbtscan
- **Web & App Scanners** β sqlmap, nikto, dirb, gobuster, feroxbuster, ffuf, httpx
- **Vulnerability Scanners** β nuclei, wpscan, wafw00f, dalfox, xsser
- **Subdomain Enumeration** β subfinder, amass, findomain, dnsenum, fierce
- **API Security** β graphql-scanner, arjun, api-fuzzer, api-schema-analyzer
- **Container Security** β trivy, clair, docker-bench-security, kube-bench, kube-hunter
- **Cloud Security** β prowler, scout-suite, cloudmapper, pacu, terrascan, checkov
- **Binary Analysis** β gdb, radare2, ghidra, objdump, strings, binwalk
- **Exploitation** β metasploit, msfvenom, pwntools, ropper, ropgadget
- **Password Cracking** β hashcat, john, hashpump
- **Forensics** β volatility, volatility3, foremost, steghide, exiftool
- **Post-Exploitation** β linpeas, winpeas, mimikatz, bloodhound, impacket, responder
- **CTF Utilities** β stegsolve, zsteg, hash-identifier, fcrackzip, pdfcrack, cyberchef
- **System Helpers** β exec, create-file, delete-file, list-files, modify-file
## Basic Usage
### Quick Start
1. **Clone & install**
```bash
git clone https://github.com/Ed1s0nZ/CyberStrikeAI.git
cd CyberStrikeAI-main
go mod download
```
2. **Set up the Python tooling stack (required for the YAML tools directory)**
A large portion of `tools/*.yaml` recipes wrap Python utilities (`api-fuzzer`, `http-framework-test`, `install-python-package`, etc.). Create the project-local virtual environment once and install the shared dependencies:
```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
The helper tools automatically detect this `venv` (or any already active `$VIRTUAL_ENV`), so the default `env_name` works out of the box unless you intentionally supply another target.
3. **Configure OpenAI-compatible access**
Either open the in-app `Settings` panel after launch or edit `config.yaml`:
```yaml
openai:
api_key: "sk-your-key"
base_url: "https://api.openai.com/v1"
model: "gpt-4o"
auth:
password: "" # empty = auto-generate & log once
session_duration_hours: 12
security:
tools_dir: "tools"
```
4. **Install the tooling you need (optional)**
```bash
# macOS
brew install nmap sqlmap nuclei httpx gobuster feroxbuster subfinder amass
# Ubuntu/Debian
sudo apt-get install nmap sqlmap nuclei httpx gobuster feroxbuster
```
AI automatically falls back to alternatives when a tool is missing.
5. **Launch**
```bash
chmod +x run.sh && ./run.sh
# or
go run cmd/server/main.go
# or
go build -o cyberstrike-ai cmd/server/main.go
```
6. **Open the console** at http://localhost:8080, log in with the generated password, and start chatting.
### Core Workflows
- **Conversation testing** β Natural-language prompts trigger toolchains with streaming SSE output.
- **Tool monitor** β Inspect running jobs, execution logs, and large-result attachments.
- **History & audit** β Every conversation and tool invocation is stored in SQLite with replay.
- **Settings** β Tweak provider keys, MCP enablement, tool toggles, and agent iteration limits.
### Built-in Safeguards
- Required-field validation prevents accidental blank API credentials.
- Auto-generated strong passwords when `auth.password` is empty.
- Unified auth middleware for every web/API call (Bearer token flow).
- Timeout and sandbox guards per tool, plus structured logging for triage.
## Advanced Usage
### Tool Orchestration & Extensions
- **YAML recipes** in `tools/*.yaml` describe commands, arguments, prompts, and metadata.
- **Directory hot-reload** β pointing `security.tools_dir` to a folder is usually enough; inline definitions in `config.yaml` remain supported for quick experiments.
- **Large-result pagination** β outputs beyond 200 KB are stored as artifacts retrievable through the `query_execution_result` tool with paging, filters, and regex search.
- **Result compression** β multi-megabyte logs can be summarized or losslessly compressed before persisting to keep SQLite lean.
**Creating a custom tool (typical flow)**
1. Copy an existing YAML file from `tools/` (for example `tools/sample.yaml`).
2. Update `name`, `command`, `args`, and `short_description`.
3. Describe positional or flag parameters in `parameters[]` so the agent knows how to build CLI arguments.
4. Provide a longer `description`/`notes` block if the agent needs extra context or post-processing tips.
5. Restart the server or reload configuration; the new tool becomes available immediately and can be enabled/disabled from the Settings panel.
### Attack-Chain Intelligence
- AI parses each conversation to assemble targets, tools, vulnerabilities, and relationships.
- The web UI renders the chain as an interactive graph with severity scoring and step replay.
- Export the chain or raw findings to external reporting pipelines.
### MCP Everywhere
- **Web mode** β ships with HTTP MCP server automatically consumed by the UI.
- **MCP stdio mode** β `go run cmd/mcp-stdio/main.go` exposes the agent to Cursor/CLI.
- **External MCP federation** β register third-party MCP servers (HTTP or stdio) from the UI, toggle them per engagement, and monitor their health and call volume in real time.
#### MCP stdio quick start
1. **Build the binary** (run from the project root):
```bash
go build -o cyberstrike-ai-mcp cmd/mcp-stdio/main.go
```
2. **Wire it up in Cursor**
Open `Settings β Tools & MCP β Add Custom MCP`, pick **Command**, then point to the compiled binary and your config:
```json
{
"mcpServers": {
"cyberstrike-ai": {
"command": "/absolute/path/to/cyberstrike-ai-mcp",
"args": [
"--config",
"/absolute/path/to/config.yaml"
]
}
}
}
```
Replace the paths with your local locations; Cursor will launch the stdio server automatically.
#### MCP HTTP quick start
1. Ensure `config.yaml` has `mcp.enabled: true` and adjust `mcp.host` / `mcp.port` if you need a non-default binding (localhost:8081 works well for local Cursor usage).
2. Start the main service (`./run.sh` or `go run cmd/server/main.go`); the MCP endpoint lives at `http://:/mcp`.
3. In Cursor, choose **Add Custom MCP β HTTP** and set `Base URL` to `http://127.0.0.1:8081/mcp`.
4. Prefer committing the setup via `.cursor/mcp.json` so teammates can reuse it:
```json
{
"mcpServers": {
"cyberstrike-ai-http": {
"transport": "http",
"url": "http://127.0.0.1:8081/mcp"
}
}
}
```
### Automation Hooks
- **REST APIs** β everything the UI uses (auth, conversations, tool runs, monitor) is available over JSON.
- **Task control** β pause/resume/stop long scans, re-run steps with new params, or stream transcripts.
- **Audit & security** β rotate passwords via `/api/auth/change-password`, enforce short-lived sessions, and restrict MCP ports at the network layer when exposing the service.
## Configuration Reference
```yaml
auth:
password: "change-me"
session_duration_hours: 12
server:
host: "0.0.0.0"
port: 8080
log:
level: "info"
output: "stdout"
mcp:
enabled: true
host: "0.0.0.0"
port: 8081
openai:
api_key: "sk-xxx"
base_url: "https://api.deepseek.com/v1"
model: "deepseek-chat"
database:
path: "data/conversations.db"
security:
tools_dir: "tools"
```
### Tool Definition Example (`tools/nmap.yaml`)
```yaml
name: "nmap"
command: "nmap"
args: ["-sT", "-sV", "-sC"]
enabled: true
short_description: "Network mapping & service fingerprinting"
parameters:
- name: "target"
type: "string"
description: "IP or domain"
required: true
position: 0
- name: "ports"
type: "string"
flag: "-p"
description: "Range, e.g. 1-1000"
```
## Project Layout
```
CyberStrikeAI/
βββ cmd/ # Server, MCP stdio entrypoints, tooling
βββ internal/ # Agent, MCP core, handlers, security executor
βββ web/ # Static SPA + templates
βββ tools/ # YAML tool recipes (100+ examples provided)
βββ img/ # Docs screenshots & diagrams
βββ config.yaml # Runtime configuration
βββ run.sh # Convenience launcher
βββ README*.md
```
## Basic Usage Examples
```
Scan open ports on 192.168.1.1
Perform a comprehensive port scan on 192.168.1.1 focusing on 80,443,22
Check if https://example.com/page?id=1 is vulnerable to SQL injection
Scan https://example.com for hidden directories and outdated software
Enumerate subdomains for example.com, then run nuclei against the results
```
## Advanced Playbooks
```
Load the recon-engagement template, run amass/subfinder, then brute-force dirs on every live host.
Use external Burp-based MCP server for authenticated traffic replay, then pass findings back for graphing.
Compress the 5 MB nuclei report, summarize critical CVEs, and attach the artifact to the conversation.
Build an attack chain for the latest engagement and export the node list with severity >= high.
```
## Changelog (Recent)
- 2025-12-07 β Added FOFA network space search engine tool (fofa_search) with flexible query parameters and field configuration.
- 2025-12-07 β Fixed positional parameter handling bug: ensure correct parameter position when using default values.
- 2025-11-20 β Added automatic compression/summarization for oversized tool logs and MCP transcripts.
- 2025-11-17 β Introduced AI-built attack-chain visualization with interactive graph and risk scoring.
- 2025-11-15 β Delivered large-result pagination, advanced filtering, and external MCP federation.
- 2025-11-14 β Optimized tool lookups (O(1)), execution record cleanup, and DB pagination.
- 2025-11-13 β Added web authentication, settings UI, and MCP stdio mode integration.
---
Need help or want to contribute? Open an issue or PRβcommunity tooling additions are welcome!
