Skip to content

README.md

Latest commit

 

History

History
724 lines (536 loc) · 26.1 KB

README.md

File metadata and controls

724 lines (536 loc) · 26.1 KB

🛡️ Hancock — CyberViser AI Security Agent

Hancock Banner

License: Apache%202.0 Python Model NVIDIA NIM Website Netlify

Automate cybersecurity through specialized LLMs — from pentesting to SOC analysis.

🌐 Website · 📖 API Docs · 📋 Business Proposal · 🐛 Report Bug · ✨ Request Feature

🚀 What is Hancock?

Hancock is CyberViser's AI-powered cybersecurity agent, fine-tuned on Mistral 7B using:

  • MITRE ATT&CK — TTPs, tactics, procedures
  • NVD/CVE — Real vulnerability data
  • Pentest Knowledge Base — Recon, exploitation, post-exploitation

It operates in nine specialist modes and exposes a clean REST API.

╔══════════════════════════════════════════════════════════╗
║  ██╗  ██╗ █████╗ ███╗   ██╗ ██████╗ ██████╗  ██████╗██╗ ║
║  ██║  ██║██╔══██╗████╗  ██║██╔════╝██╔═══██╗██╔════╝██║ ║
║  ███████║███████║██╔██╗ ██║██║     ██║   ██║██║     ██║ ║
║  ██╔══██║██╔══██║██║╚██╗██║██║     ██║   ██║██║     ██╚╗║
║  ██║  ██║██║  ██║██║ ╚████║╚██████╗╚██████╔╝╚██████╗╚═╝║║
║  ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝ ╚═════╝  ╚═════╝   ║
║          CyberViser — Pentest + SOC Specialist           ║
╚══════════════════════════════════════════════════════════╝

📋 Table of Contents

✨ Features

Mode Description Status
🔴 Pentest Specialist Recon, exploitation, CVE analysis, PTES reporting ✅ Live
🔵 SOC Analyst Alert triage, SIEM queries, PICERL IR, Sigma/YARA ✅ Live
⚡ Auto Context-aware switching between pentest + SOC ✅ Live
💻 Code Security code: YARA, KQL, SPL, Sigma, Python, Bash ✅ Live
👔 CISO Compliance, risk reporting, board summaries, gap analysis ✅ Live
🔍 Sigma Sigma detection rule authoring with ATT&CK tagging ✅ Live
🦠 YARA YARA malware detection rule authoring ✅ Live
🔎 IOC Threat intelligence enrichment for IOCs ✅ Live
🌍 OSINT IP/domain geolocation, infrastructure mapping, predictive analytics ✅ Live
🔐 GraphQL Security GraphQL auth/authz testing, IDOR detection, JWT security ✅ Live

⚡ Quick Start

1. Install dependencies

git clone https://github.com/0ai-Cyberviser/Hancock.git
cd Hancock
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

2. Configure your API key

cp .env.example .env
# Edit .env and add your NVIDIA API key
# Get one free at: https://build.nvidia.com

3. Run the CLI

export NVIDIA_API_KEY="nvapi-..."
python hancock_agent.py

4. Or run as a REST API server

python hancock_agent.py --server --port 5000

5. Build the training dataset

# v2 dataset (pentest + SOC):
python hancock_pipeline.py --phase all

# v3 dataset (+ CISA KEV + Atomic Red Team + GitHub Advisories):
python hancock_pipeline.py --phase 3

6. Fine-tune Hancock on Mistral 7B

python hancock_finetune.py

🌐 API Reference

Start the server: python hancock_agent.py --server

/internal/diagnostics stays hidden unless HANCOCK_ENABLE_INTERNAL_DIAGNOSTICS is set to a truthy value (1, true, yes, or on). When enabled, it still requires HANCOCK_API_KEY to be configured and uses the normal Bearer auth and rate-limit checks.

Endpoints

Method Endpoint Description
GET /health Agent status and capabilities
GET /metrics Prometheus-compatible request counters
GET /internal/diagnostics Auth-gated internal runtime metadata
GET /v1/agents All agent system prompts and defaults
POST /v1/chat Conversational AI with history + streaming
POST /v1/ask Single-shot question
POST /v1/triage SOC alert triage + MITRE ATT&CK mapping
POST /v1/hunt Threat hunting query generator (Splunk/Elastic/Sentinel)
POST /v1/respond PICERL incident response playbook
POST /v1/code Security code generation (YARA/Sigma/KQL/SPL)
POST /v1/ciso CISO advisory: risk, compliance, board reports, gap analysis
POST /v1/sigma Sigma detection rule generator
POST /v1/yara YARA malware detection rule generator
POST /v1/ioc IOC threat intelligence enrichment
POST /v1/geolocate OSINT geolocation for IPs/domains
POST /v1/predict-locations Predict future threat infrastructure locations
POST /v1/map-infrastructure Map and cluster threat infrastructure geographically
POST /v1/webhook Ingest alerts from Splunk/Elastic/Sentinel/CrowdStrike

Examples

Alert Triage:

curl -X POST http://localhost:5000/v1/triage \
  -H "Content-Type: application/json" \
  -d '{"alert": "Mimikatz detected on DC01 at 03:14 UTC"}'

Threat Hunting (Splunk):

curl -X POST http://localhost:5000/v1/hunt \
  -H "Content-Type: application/json" \
  -d '{"target": "lateral movement via PsExec", "siem": "splunk"}'

Sigma Rule Generation:

curl -X POST http://localhost:5000/v1/sigma \
  -H "Content-Type: application/json" \
  -d '{"description": "Detect LSASS memory dump", "logsource": "windows sysmon", "technique": "T1003.001"}'

YARA Rule Generation:

curl -X POST http://localhost:5000/v1/yara \
  -H "Content-Type: application/json" \
  -d '{"description": "Cobalt Strike beacon default HTTP profile", "file_type": "PE"}'

Internal Diagnostics:

curl http://localhost:5000/internal/diagnostics \
  -H "Authorization: Bearer $HANCOCK_API_KEY"

IOC Enrichment:

curl -X POST http://localhost:5000/v1/ioc \
  -H "Content-Type: application/json" \
  -d '{"indicator": "185.220.101.35", "type": "ip"}'

OSINT Geolocation:

curl -X POST http://localhost:5000/v1/geolocate \
  -H "Content-Type: application/json" \
  -d '{"indicators": ["185.220.101.35", "evil.example.com"]}'

Predict Threat Infrastructure Locations:

curl -X POST http://localhost:5000/v1/predict-locations \
  -H "Content-Type: application/json" \
  -d '{"historical_data": [{"indicator": "185.220.101.35", "indicator_type": "ip", "geo_results": [{"ip": "185.220.101.35", "country_code": "NL", "asn": "AS9009"}], "first_seen": "2025-01-01T00:00:00Z", "last_seen": "2025-03-01T00:00:00Z"}]}'

Map Threat Infrastructure:

curl -X POST http://localhost:5000/v1/map-infrastructure \
  -H "Content-Type: application/json" \
  -d '{"indicators": ["185.220.101.35", "45.33.32.156", "93.184.216.34"]}'

GraphQL Security Testing:

# Generate GraphQL security knowledge base
python collectors/graphql_security_kb.py

# Run GraphQL security tests (requires authorization)
python collectors/graphql_security_tester.py \
  --url https://api.example.com/graphql \
  --token <jwt-token> \
  --verbose \
  --report graphql_security_report.json

CISO Board Summary:

curl -X POST http://localhost:5000/v1/ciso \
  -H "Content-Type: application/json" \
  -d '{"question": "Summarise top 5 risks for the board", "output": "board-summary", "context": "50-person SaaS, AWS"}'

Incident Response Playbook:

curl -X POST http://localhost:5000/v1/respond \
  -H "Content-Type: application/json" \
  -d '{"incident": "ransomware"}'

📖 Full OpenAPI 3.1.0 spec: docs/openapi.yaml · Interactive API Docs

CLI Commands

/mode pentest   — switch to Pentest Specialist
/mode soc       — switch to SOC Analyst
/mode auto      — combined persona (default)
/mode code      — security code (Qwen Coder 32B)
/mode ciso      — CISO strategy & compliance
/mode sigma     — Sigma detection rule authoring
/mode yara      — YARA malware detection rule authoring
/mode ioc       — IOC threat intelligence enrichment
/mode osint     — OSINT geolocation intelligence analyst
/clear          — clear conversation history
/history        — show history
/model <id>     — switch active model
/exit           — quit

🔧 Environment Variables

Copy .env.example to .env and configure:

cp .env.example .env
Variable Description Default
HANCOCK_LLM_BACKEND Backend engine: ollama | nvidia | openai ollama
OLLAMA_BASE_URL Ollama server URL http://localhost:11434
OLLAMA_MODEL Ollama chat model llama3.1:8b
OLLAMA_CODER_MODEL Ollama code generation model qwen2.5-coder:7b
NVIDIA_API_KEY NVIDIA NIM API key (get free) —
OPENAI_API_KEY OpenAI API key (fallback) —
OPENAI_ORG_ID OpenAI organization ID —
HANCOCK_MODEL NIM/OpenAI model override mistralai/mistral-7b-instruct-v0.3
HANCOCK_CODER_MODEL NIM/OpenAI code model qwen/qwen2.5-coder-32b-instruct
HANCOCK_PORT REST API server port 5000
HANCOCK_API_KEY Bearer token for API auth (empty = no auth) —
HANCOCK_RATE_LIMIT Max requests per IP per minute 60
HANCOCK_ENABLE_INTERNAL_DIAGNOSTICS Enable GET /internal/diagnostics for operators disabled
HANCOCK_WEBHOOK_SECRET HMAC-SHA256 secret for /v1/webhook —
HANCOCK_SLACK_WEBHOOK Slack incoming webhook URL —
HANCOCK_TEAMS_WEBHOOK Microsoft Teams incoming webhook URL —
IPINFO_TOKEN ipinfo.io API token (OSINT geolocation primary source) —
HANCOCK_ALLOW_INSECURE_GEOIP Allow plaintext ip-api.com fallback for OSINT lookups disabled
ABUSEIPDB_KEY AbuseIPDB API key (threat enrichment) —
VT_API_KEY VirusTotal API key (threat enrichment) —

🔀 Backend Selection

Hancock uses one canonical backend selection strategy:

  1. Primary backend from HANCOCK_LLM_BACKEND (default: ollama).
    • ollama uses OLLAMA_BASE_URL + OLLAMA_MODEL / OLLAMA_CODER_MODEL
    • nvidia uses NVIDIA NIM (NVIDIA_API_KEY) and HANCOCK_MODEL / HANCOCK_CODER_MODEL
    • openai uses OPENAI_API_KEY and OPENAI_MODEL / OPENAI_CODER_MODEL
  2. Automatic runtime fallback: if a primary Ollama or NVIDIA request fails, Hancock retries with OpenAI when OPENAI_API_KEY is configured.
  3. Startup fallback: if the configured backend cannot initialize, Hancock attempts OpenAI before exiting.

This fallback order is therefore: configured primary (ollama/nvidia/openai) → OpenAI (if configured) → exit with configuration error.

🌍 OSINT Geolocation Intelligence

The OSINT module (collectors/osint_geolocation.py) provides multi-source IP/domain geolocation, threat infrastructure mapping, geographic clustering, and predictive location analytics.

Capabilities

  • Multi-source geolocation — ipinfo.io (primary HTTPS), ipapi.co (secondary HTTPS), optional plaintext ip-api.com fallback
  • Threat enrichment — AbuseIPDB + VirusTotal integration for risk scoring
  • Infrastructure mapping — Geographic clustering via Haversine distance, ASN/ISP grouping
  • Predictive analytics — Forecast future threat infrastructure locations based on historical patterns
  • Risk scoring — Bulletproof ASN detection, country cyber-risk index (see collectors/osint_geolocation.py for the full list)

CLI Mode

python hancock_agent.py
# Then type: /mode osint

API Endpoints

Method Endpoint Description
POST /v1/geolocate Geolocate a list of IP/domain indicators
POST /v1/predict-locations Predict future threat infrastructure locations
POST /v1/map-infrastructure Map and cluster indicators geographically

📖 Full guide: docs/osint-geolocation.md

🛠️ Security Tool Integrations

Hancock integrates with common security tools for automated reconnaissance and testing:

Tool Module Description
Nmap collectors/nmap_recon.py Port scanning, service enumeration, XML-to-JSON parsing
SQLMap collectors/sqlmap_exploit.py Automated SQL injection testing via SQLMap API
Burp Suite collectors/burp_post_exploit.py Active scanning via Burp REST API

GraphQL Security Testing

The GraphQL security framework provides automated penetration testing:

# Generate GraphQL security knowledge base
python collectors/graphql_security_kb.py

# Run GraphQL security tests
python collectors/graphql_security_tester.py \
  --url https://api.example.com/graphql \
  --token <jwt-token> \
  --verbose \
  --report graphql_security_report.json

Tests include: introspection detection, IDOR/BOLA, JWT vulnerabilities, mutation authorization bypass, field-level auth flaws, and rate limiting bypasses.

📖 Guides: docs/graphql-security-guide.md · docs/graphql-security-quickstart.md · TOOL_INTEGRATION.md

📦 Client SDKs

Python SDK

pip install openai python-dotenv
python clients/python/hancock_cli.py
# or: make client-python

See clients/python/README.md for library usage.

Node.js SDK

cd clients/nodejs && npm install
node clients/nodejs/hancock.js
# or: make client-node

See clients/nodejs/README.md for library usage.

📊 Monitoring & Observability

Prometheus Metrics

The /metrics endpoint exposes Prometheus-compatible metrics:

Metric Type Description
hancock_requests_total Counter Total requests
hancock_errors_total Counter Total 4xx/5xx errors
hancock_requests_by_endpoint Counter Requests per endpoint
hancock_requests_by_mode Counter Requests per specialist mode

Additional metrics (histograms, gauges) are available via monitoring/metrics_exporter.py when integrated as middleware — see docs/monitoring.md.

Health Checks

The /health endpoint checks backend availability (Ollama, NVIDIA NIM, or OpenAI) with 30-second TTL caching.

Pre-flight validation:

python deploy/startup_checks.py

📖 Full guide: docs/monitoring.md · docs/performance.md

🚢 Deployment

Docker

# Build image
docker build -t cyberviser/hancock:latest .
# or: make docker

# Run with Docker Compose (Ollama + Hancock)
docker-compose up -d
# or: make docker-up

Kubernetes / Helm

# Apply manifests directly
kubectl apply -f deploy/k8s/

# Or install via Helm
helm install hancock deploy/helm/ -f deploy/helm/values.yaml

Includes HPA (2–10 replicas), ConfigMap, and Secret manifests.

Terraform (AWS ECS Fargate)

cd deploy/terraform
terraform init && terraform apply

Fly.io

flyctl deploy --config fly.toml
# or: make fly-deploy

📖 Guides: docs/deployment.md · docs/production-checklist.md · docs/ci-cd.md

🔒 Fuzzing & Security Testing

Hancock includes atheris-based fuzz targets for continuous security testing:

Target Module Under Test
fuzz/fuzz_nvd_parser.py NVD CVE parser
fuzz/fuzz_mitre_parser.py MITRE ATT&CK parser
fuzz/fuzz_formatter.py JSONL formatter
fuzz/fuzz_formatter_v3.py v3 formatter
fuzz/fuzz_api_inputs.py API endpoint inputs
fuzz/fuzz_webhook_signature.py Webhook HMAC verification
fuzz/fuzz_ghsa_parser.py GitHub Security Advisory parser
fuzz/fuzz_xml_parsing.py XML parsing 
# Run all fuzz targets (60s each)
make fuzz

# Run a specific fuzz target
make fuzz-target TARGET=fuzz_nvd_parser

CIFuzz runs on every PR via .github/workflows/cifuzz.yml and daily continuous fuzzing runs via .github/workflows/continuous-fuzz.yml.

⚙️ CI/CD Pipelines

Workflow Trigger Description
test.yml Push / PR Unit and integration test suite
security.yml Push / PR Bandit SAST, pip-audit, Trivy container scan
codeql.yml Push / PR CodeQL static analysis
cifuzz.yml PR CIFuzz atheris fuzz testing
continuous-fuzz.yml Daily schedule Extended continuous fuzzing
benchmark.yml PR Latency regression benchmarking
python-package.yml Push Package distribution
deploy.yml Push to main Automatic deployment to staging
finetune.yml Manual Model fine-tuning pipeline
release.yml Tag GitHub release automation

🤗 Hugging Face Spaces

Hancock is available as a free Gradio web UI on Hugging Face Spaces:

https://huggingface.co/spaces/cyberviser/hancock

To self-host the Spaces app, set these environment variables:

Variable Description
HANCOCK_API_URL URL of your deployed Hancock instance
HANCOCK_API_KEY Bearer token (optional, leave blank if auth is disabled) 
python spaces_app.py

🤖 Fine-Tuning

Hancock uses LoRA fine-tuning on Mistral 7B — trained on a multi-source cybersecurity dataset (MITRE ATT&CK + NVD CVEs + SOC/Pentest KB + CISA KEV + Atomic Red Team + GitHub Security Advisories).

⚡ One-Click: Colab / Kaggle (Free T4)

Open In Colab

Works on both Google Colab and Kaggle — auto-detects environment:

  1. Click the badge above (or import Hancock_Universal_Finetune.ipynb on Kaggle)
  2. Enable GPU (Colab: Runtime → T4 GPU / Kaggle: Settings → Accelerator → T4)
  3. Run all (~30 min)
  4. Downloads GGUF Q4_K_M at end — run locally with Ollama

Or use the CLI script directly:

python hancock_finetune_v3.py --steps 300 --export-gguf --push-to-hub

CPU Fine-Tuning (No GPU Required)

Install the optional training stack, then run on any machine to fine-tune TinyLlama-1.1B with LoRA:

make finetune-install

# Quick test (10 steps, ~40 min)
python hancock_cpu_finetune.py --debug

# Full run (500 steps, ~25 hr on 16-core CPU)
python hancock_cpu_finetune.py --max-steps 500

# Load and test the saved adapter
python hancock_cpu_finetune.py --test

Pre-trained adapter: hancock-cpu-adapter/ — TinyLlama-1.1B + LoRA (r=8, eval_loss=2.084)

Other GPU Options

Platform GPU Cost Script
Google Colab T4 16GB Free (15 hr/day) Hancock_Universal_Finetune.ipynb
Kaggle T4 16GB Free (30 hr/week) Hancock_Universal_Finetune.ipynb
Modal.com T4/A10G Free $30/mo modal run train_modal.py
Any GPU server Any Varies python hancock_finetune_gpu.py

After Training — Run Locally

# Load fine-tuned model in Ollama
ollama create hancock -f Modelfile.hancock-finetuned
ollama run hancock

Training Data

Dataset Samples Sources Command
hancock_v2.jsonl 1,375 MITRE ATT&CK + NVD CVE + Pentest KB + SOC KB python hancock_pipeline.py --phase 2
hancock_v3.jsonl 5,670 v2 + CISA KEV + Atomic Red Team + GitHub Security Advisories python hancock_pipeline.py --phase 3 
# Generate latest v3 dataset (internet required)
python hancock_pipeline.py --phase 3

# Or offline-only (static KB, no internet)
python hancock_pipeline.py --kb-only
data/
├── hancock_pentest_v1.jsonl    # Pentest training data (MITRE + CVE + KB)
├── hancock_v2.jsonl            # v2 dataset — pentest + SOC
└── hancock_v3.jsonl            # v3 dataset — + CISA KEV + Atomic Red Team + GHSA (build with --phase 3)

collectors/
├── mitre_collector.py          # Fetches MITRE ATT&CK TTPs
├── nvd_collector.py            # Fetches NVD/CVE vulnerability data
├── pentest_kb.py               # Pentest knowledge base Q&A
├── soc_collector.py / soc_kb.py
├── cisa_kev_collector.py       # CISA Known Exploited Vulnerabilities
├── atomic_collector.py         # Atomic Red Team test cases
├── ghsa_collector.py           # GitHub Security Advisories
├── graphql_security_kb.py      # GraphQL auth/authz vulnerability KB
└── graphql_security_tester.py  # GraphQL security testing framework

formatter/
├── to_mistral_jsonl.py         # v1 formatter
├── to_mistral_jsonl_v2.py      # v2 formatter
└── formatter_v3.py             # v3 formatter — merges all sources

🗺️ Roadmap

Phase Focus Status
Phase 1 Pentest Specialist + SOC REST API ✅ Live
Phase 2 SOC deep specialization + v3 dataset (KEV/Atomic/GHSA) ✅ Live
Phase 3 CISO strategy + compliance automation ✅ Live
Phase 4 Enterprise platform + SIEM/SOAR integrations 📋 Planned

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

  1. Fork the repo
  2. Create a feature branch: git checkout -b feat/my-feature
  3. Commit your changes: git commit -m 'feat: add my feature'
  4. Push and open a PR

📄 License

CyberViser / 0ai-Cyberviser Project License — see LICENSE for repository terms and OWNERSHIP.md for the control notice.

  • ✅ View and study the code
  • ✅ Run locally for personal or internal non-commercial evaluation
  • ✅ Submit contributions for maintainer review
  • ❗ Commercial or production use requires a separate written agreement
  • ❗ Branding, repository administration, and merge approval remain controlled by Johnny Watters / 0ai-Cyberviser
  • ❗ Third-party materials and non-assigned contributions remain governed by their own terms
  • ❗ Maintainers may require additional written rights confirmation before merging a contribution

Project contacts: 0ai@cyberviserai.com · cyberviser@proton.me

Maintained by Johnny Watters (0ai-Cyberviser) · Powered by NVIDIA NIM · Mistral 7B · LoRA

Sponsors & Supporters

Hancock Bronze Supporter — $5/mo
Buy Me a Coffee

Scan to join instantly: Hancock Bronze QR

Perks you get:

  • Early access to new modes & preview builds
  • Exclusive technical deep-dives & roadmap votes
  • Priority support + permanent name in Sponsors section
  • Private Discord “Hancock Bronze” role & members-only channel

Thank you to every Bronze Supporter powering the next evolution of Hancock.

Funding & Sponsors

Support Hancock development

Every contribution directly funds Hybrid RAG, secure sandboxes, fine-tuning, and Phase 4 enterprise features. Thank you!

GitHub Sponsors

Open Collective