🛡️ Hancock — CyberViser AI Security Agent

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
• Quick Start
• API Reference
• CLI Commands
• Environment Variables
• OSINT Geolocation Intelligence
• Security Tool Integrations
• Client SDKs
• Monitoring & Observability
• Deployment
• Fuzzing & Security Testing
• CI/CD Pipelines
• Hugging Face Spaces
• Fine-Tuning
• Roadmap
• Contributing
• License

---

✨ 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/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

Endpoints

Method	Endpoint	Description
GET	/health	Agent status and capabilities
GET	/metrics	Prometheus-compatible request counters
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"}'

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 '{"indicators": ["185.220.101.35", "45.33.32.156"], "campaign": "APT29-infra"}'

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 NVIDIA NIM 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_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 fallback)	—
ABUSEIPDB_KEY	AbuseIPDB API key (threat enrichment)	—
VT_API_KEY	VirusTotal API key (threat enrichment)	—

---

🌍 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 — ip-api.com (primary), ipinfo.io (fallback), ipapi.co (secondary 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)

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)

Run on any machine — trains TinyLlama-1.1B with LoRA (adapter already included):

# 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 Proprietary License — see LICENSE for full terms.

• ✅ View and study the code
• ✅ Run locally for personal/research use
• ✅ Submit contributions (assigned to CyberViser)
• ❌ Commercial use without a written license agreement
• ❌ Redistribution or reselling
• ❌ Building competing products or services
• ❌ Training AI/ML models on the code or datasets
• ❌ White-labeling or removing CyberViser branding

For commercial licensing: contact@cyberviser.ai

---

Built by CyberViser · Powered by NVIDIA NIM · Mistral 7B · LoRA