Hancock API

REST API reference for the CyberViser Hancock AI Security Agent

Start the server with python hancock_agent.py --server or make server. Requires a valid NVIDIA_API_KEY in your .env.

Base URL

    # Default local

    http://localhost:5000

    # Docker

    http://your-server:5000

All endpoints accept and return application/json. No authentication is required on the local server — add your own reverse proxy + auth for production.

GET /health

Returns the agent status, loaded model, and available endpoints.

GET /health No params

    $ curl http://localhost:5000/health

    {

      "status": "ok",

      "agent": "Hancock",

      "model": "mistralai/mistral-7b-instruct-v0.3",

      "company": "CyberViser",

      "modes": ["pentest", "soc", "auto"],

      "endpoints": ["/v1/chat", "/v1/ask", "/v1/triage", "/v1/hunt", "/v1/respond"]

    }

POST /v1/chat

Conversational AI with multi-turn history. Choose a specialist mode per request.

POST /v1/chat Supports streaming

    // Request body

    {

      "message": "How do I enumerate SMB shares on a target?",

      "mode": "pentest",              // "auto" | "pentest" | "soc"

      "history": [],                   // array of {role, content} pairs

      "stream": false                 // true for SSE streaming

    }

Field	Type	Required	Description
`message`	string	required	User's message
`mode`	string	optional	`auto` (default), `pentest`, or `soc`
`history`	array	optional	Previous conversation turns
`stream`	boolean	optional	Enable SSE streaming (default: false)

POST /v1/ask

Single-shot question — no history, fastest response time.

POST /v1/ask

    $ curl -s -X POST http://localhost:5000/v1/ask \

      -H "Content-Type: application/json" \

      -d '{"question": "What is CVE-2021-44228?", "mode": "pentest"}'

POST /v1/triage

Submit a raw security alert. Hancock returns severity classification, MITRE ATT&CK mapping, TP/FP verdict, and immediate containment actions.

POST /v1/triage SOC mode

    $ curl -X POST http://localhost:5000/v1/triage \

      -H "Content-Type: application/json" \

      -d '{"alert": "Mimikatz.exe detected on DC01 at 03:14 UTC. Process: lsass dump."}'

    // Response

    {

      "triage": "**Severity: CRITICAL**\n\nMITRE: T1003 (OS Credential Dumping)...",

      "model": "mistralai/mistral-7b-instruct-v0.3"

    }

Field	Type	Required	Description
`alert`	string	required	Raw alert text from SIEM, EDR, or IDS/IPS

POST /v1/hunt

Generate production-ready threat hunting queries for Splunk, Elastic, or Microsoft Sentinel.

POST /v1/hunt SOC mode

    $ curl -X POST http://localhost:5000/v1/hunt \

      -H "Content-Type: application/json" \

      -d '{"target": "lateral movement via PsExec", "siem": "splunk"}'

Field	Type	Required	Description
`target`	string	required	TTP or behavior to hunt (e.g. "Kerberoasting", "DNS tunneling")
`siem`	string	optional	`splunk` (default), `elastic`, or `sentinel`

POST /v1/respond

Generate a full PICERL incident response playbook for any incident type.

POST /v1/respond SOC mode

    $ curl -X POST http://localhost:5000/v1/respond \

      -H "Content-Type: application/json" \

      -d '{"incident": "ransomware"}'

    // Returns full PICERL playbook:

    // Prepare → Identify → Contain → Eradicate → Recover → Lessons Learned

Field	Type	Required	Description
`incident`	string	required	Incident type (e.g. `ransomware`, `BEC`, `data exfiltration`)

POST /v1/code

Generate production-ready security code using Qwen 2.5 Coder 32B. Outputs Python, Bash, PowerShell, Go, KQL, SPL, YARA, and Sigma rules.

POST /v1/code Code mode

    $ curl -X POST http://localhost:5000/v1/code \

      -H "Content-Type: application/json" \

      -d '{"task": "YARA rule for Emotet dropper", "language": "yara"}'

    // Response

    {

      "code": "rule Emotet_Dropper { ... }",

      "model": "qwen/qwen2.5-coder-32b-instruct",

      "language": "yara"

    }

Field	Type	Required	Description
`task`	string	required	What to build (e.g. "KQL query for Pass-the-Hash", "YARA rule for Cobalt Strike")
`language`	string	optional	`python`, `bash`, `powershell`, `go`, `kql`, `spl`, `yara`, `sigma`

POST /v1/ciso

AI CISO advisor — risk management, compliance (ISO 27001, SOC 2, NIST CSF, PCI-DSS), board reporting, gap analysis, and security strategy. Use output to control the response format.

POST /v1/ciso CISO mode

    $ curl -X POST http://localhost:5000/v1/ciso \

      -H "Content-Type: application/json" \

      -d '{"question":"What controls should we prioritise for ISO 27001 certification?","output":"gap-analysis","context":"50-person SaaS company, AWS, no current certifications"}'

    // Response

    {

      "advice": "| Control | Current State | Target State | Gap | Priority |\n...",

      "output": "gap-analysis",

      "model": "mistralai/mistral-7b-instruct-v0.3"

    }

Field	Type	Required	Description
`question`	string	required	Risk or compliance question. Also accepts `query` or `message` aliases.
`output`	string	optional	`advice` (default) · `report` · `gap-analysis` · `board-summary`
`context`	string	optional	Organisation context: size, industry, current frameworks, cloud provider, etc.

Use output: "board-summary" to get a concise ≤300-word executive-ready summary, or "gap-analysis" for a structured control gap table.

POST /v1/sigma

Sigma detection rule generator — converts a TTP description or threat intelligence into a production-ready Sigma YAML rule, complete with MITRE ATT&CK tags, logsource, detection logic, false-positive analysis, and severity level.

POST /v1/sigma Sigma mode

    $ curl -X POST http://localhost:5000/v1/sigma \

      -H "Content-Type: application/json" \

      -d '{"description":"Detect PowerShell encoded command execution","logsource":"windows sysmon","technique":"T1059.001"}'

    // Response

    {

      "rule": "title: PowerShell Encoded Command Execution\nid: ...\ntags:\n  - attack.t1059.001\nlogsource:\n  product: windows\n  service: sysmon\n...",

      "logsource": "windows sysmon",

      "technique": "T1059.001",

      "model": "mistralai/mistral-7b-instruct-v0.3"

    }

Field	Type	Required	Description
`description`	string	required	TTP or behaviour to detect. Also accepts `ttp` or `query` aliases.
`logsource`	string	optional	Log source hint — e.g. `windows sysmon`, `linux auditd`, `aws cloudtrail`, `azure activity`
`technique`	string	optional	MITRE ATT&CK technique ID — e.g. `T1059.001`. Auto-added to Sigma `tags` field.

The response includes the full Sigma YAML rule followed by an explanation of what it detects and tuning recommendations to reduce false positives.

POST /v1/yara

YARA malware detection rule generator — converts a malware description or sample analysis into a production-ready YARA rule with meta, string patterns, and condition logic. Uses pe/elf modules where appropriate.

POST /v1/yara YARA mode

    $ curl -X POST http://localhost:5000/v1/yara \

      -H "Content-Type: application/json" \

      -d '{"description":"Cobalt Strike beacon — default malleable C2 HTTP profile","file_type":"PE"}'

    // Response

    {

      "rule": "rule CobaltStrike_Beacon_Default_HTTP {\n  meta:\n    description = \"...\"\n  strings:\n    ...\n  condition:\n    ...\n}",

      "file_type": "PE",

      "model": "mistralai/mistral-7b-instruct-v0.3"

    }

Field	Type	Required	Description
`description`	string	required	Malware family, behaviour, or sample to detect. Also accepts `malware` or `query` aliases.
`file_type`	string	optional	File type hint — `PE`, `Office macro`, `PDF`, `script`, `shellcode`, `memory`
`hash`	string	optional	Known SHA256 sample hash — included in rule `meta` section

Set HANCOCK_WEBHOOK_SECRET to enable HMAC-SHA256 signature verification on /v1/webhook — sign requests with X-Hancock-Signature: sha256=<hex>.

POST /v1/ioc

Threat intelligence enrichment for an indicator of compromise — IP address, domain, URL, file hash (MD5/SHA256), or email address.

POST /v1/ioc

Request Body

Field	Type	Required	Description
`indicator`	string	required*	The IOC value. Also accepts `ioc` or `query` as aliases.
`type`	string	optional	Indicator type hint — `ip`, `domain`, `url`, `sha256`, `md5`, `email`, `auto`
`context`	string	optional	Additional context — e.g. "found in ransomware incident"

Example

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

Response

{
  "indicator": "185.220.101.35",
  "type": "ip",
  "report": "**Indicator:** 185.220.101.35\n**Type:** IP Address (Tor exit node)...",
  "model": "mistralai/mistral-7b-instruct-v0.3"
}

POST /v1/webhook

SIEM/EDR push webhook — auto-triage incoming alerts. Optionally forwards results to Slack or Microsoft Teams via HANCOCK_SLACK_WEBHOOK / HANCOCK_TEAMS_WEBHOOK env vars.

POST /v1/webhook SOC mode

    $ curl -X POST http://localhost:5000/v1/webhook \

      -H "Content-Type: application/json" \

      -d '{"source":"splunk","alert":"Mimikatz.exe on DC01","severity":"critical"}'

    // Response

    {

      "status": "triaged",

      "source": "splunk",

      "severity": "critical",

      "triage": "**CRITICAL** — T1003 OS Credential Dumping...",

      "model": "mistralai/mistral-7b-instruct-v0.3"

    }

Field	Type	Required	Description
`alert`	string	required	Raw alert text from SIEM, EDR, or IDS/IPS
`source`	string	optional	Alert origin: `splunk`, `elastic`, `sentinel`, `crowdstrike`, etc.
`severity`	string	optional	Reported severity: `critical`, `high`, `medium`, `low`

Set HANCOCK_SLACK_WEBHOOK and/or HANCOCK_TEAMS_WEBHOOK env vars to auto-forward triage results to your SOC channel.

Python SDK

Install and use the official Python client from clients/python/.

    $ pip install openai python-dotenv

    $ export NVIDIA_API_KEY=nvapi-...

    # security mode

    from hancock_client import HancockClient

    h = HancockClient()

    print(h.ask("Explain CVE-2021-44228"))

    # code generation mode

    print(h.code("YARA rule for Emotet dropper", language="yara"))

Node.js SDK

Install and use the official Node.js client from clients/nodejs/.

    $ cd clients/nodejs && npm install

    $ export NVIDIA_API_KEY=nvapi-...

    // One-shot code generation

    node hancock.js --mode code --task "write a KQL query for Pass-the-Hash"

    // Interactive CLI

    node hancock.js --mode code

    [code] > write a Sigma rule for Kerberoasting

Specialist Modes

Mode	Best For	Persona	Model
`pentest`	Offensive security, recon, exploitation, CVE research	Elite red team operator	Mistral 7B
`soc`	Alert triage, SIEM queries, IR, threat hunting	SOC Tier-2/3 analyst	Mistral 7B
`auto`	Mixed tasks — auto-detects context	Combined persona	Mistral 7B
`code`	YARA/Sigma rules, KQL/SPL, exploit PoCs, CTF scripts	Security code specialist	Qwen 2.5 Coder 32B

Error Handling

All endpoints return HTTP 400 for missing required fields and HTTP 500 for upstream model errors.

    // 400 Bad Request

    { "error": "message required" }

    // 500 Internal Server Error (model/API issue)

    { "error": "upstream model error: ..." }