Raven

What Raven is, in one screen

Raven accepts a suspicious file, copies it into an isolated Docker container, and gives Claude a small set of sandboxed tools to investigate it. The agent deobfuscates the sample, recovers encryption keys, decrypts the hidden payload, decompiles it, and extracts indicators of compromise — then a Snowflake-backed RAG chat lets an analyst interrogate the findings in plain language.

The one thing it proves

On its reference sample, the pipeline recovered all four stages of a real threat: an obfuscated 4 MB JScript dropper → hidden PowerShell with an AMSI bypass that disables Defender → an AES-256-CBC-encrypted payload → a reflectively-loaded .NET FTP infostealer/RAT. It pulled the AES key and IV, the C2 host and exfiltration credentials, and the full capability set (keylogging, clipboard capture, credential theft from 20+ applications) — entirely from static analysis, decompiling with ILSpy rather than running the malware.

The stack, precisely labeled

How the pieces fit together

The FastAPI orchestrator never analyzes anything itself. It copies the sample into the sandbox container, spawns the agent pipeline as a subprocess, and streams the agent's tool calls back to the browser as a live event log. The agent is the analyst; the tools are its hands.

%%{init: {'theme':'base','themeVariables':{'background':'#0c0c0e','primaryColor':'#151517','primaryTextColor':'#e6e6e6','primaryBorderColor':'#00ff41','lineColor':'#555','secondaryColor':'#111','tertiaryColor':'#0a0a0a','clusterBkg':'#0c0c0e','clusterBorder':'#262626','fontFamily':'JetBrains Mono, monospace','fontSize':'13px','textColor':'#c0c0c0'}}}%%
flowchart TB
  subgraph CLIENT["Browser · Next.js 16"]
    UI["Dashboard · streaming event log"]
    CHAT["RAG chat panel"]
  end
  subgraph API["FastAPI orchestrator"]
    UP["/analyze — upload + docker cp"]
    ST["/status — stream events"]
    RP["/report — structured findings"]
    CH["/chat — RAG"]
  end
  subgraph AGENT["Agent pipeline (subprocess)"]
    CL["Claude Sonnet
Claude Agent SDK"]
    T1["sandbox
(docker exec)"]
    T2["host_analyze
(host bash)"]
    T3["extract_file
(docker cp out)"]
  end
  subgraph ISO["Isolation + tooling"]
    BOX["Docker: malware-sandbox"]
    HOST["Host: pefile · ILSpy"]
  end
  subgraph DATA["Findings + RAG"]
    WS[("workspace/
findings · events")]
    SNOW[("Snowflake Cortex
/ SQLite fallback")]
  end
  UI --> UP & ST & RP
  CHAT --> CH
  UP --> CL
  CL --> T1 & T2 & T3
  T1 --> BOX
  T2 --> HOST
  T3 --> BOX
  CL --> WS
  WS -->|"regex IOC parse"| RP
  WS -->|"ingest"| SNOW
  CH --> SNOW
  CH -->|"grounded answer"| CL
  ST -.->|"tool-call events"| UI

Fig. 1 — Component architecture. The agent's tools straddle two zones: sandbox and host (see §4).

The analysis run, step by step

The pipeline is a fixed sequence of prompts. Each step asks the agent to perform one concrete action with one tool, so the run is legible and every move shows up in the event stream.

%%{init: {'theme':'base','themeVariables':{'background':'#0c0c0e','primaryColor':'#151517','primaryTextColor':'#e6e6e6','primaryBorderColor':'#00ff41','lineColor':'#555','actorBkg':'#151517','actorBorder':'#00ff41','actorTextColor':'#e6e6e6','signalColor':'#666','signalTextColor':'#c0c0c0','noteBkgColor':'#111','noteTextColor':'#c0c0c0','noteBorderColor':'#333','fontFamily':'JetBrains Mono, monospace','fontSize':'12px'}}}%%
sequenceDiagram
  participant U as Analyst
  participant A as FastAPI
  participant C as Claude (agent)
  participant S as Sandbox (Docker)
  participant H as Host tools

  U->>A: POST /analyze (upload)
  A->>S: docker cp sample
  A->>C: run pipeline (subprocess)
  C->>S: hash + read obfuscated JS
  C->>C: strip noise, base64 + UTF-16LE decode → PowerShell
  C->>C: recover AES key/IV, AES-256-CBC decrypt
  C->>H: extract_file → decrypted .NET binary
  C->>H: pefile + ILSpy decompile + grep IOCs
  C->>A: write findings report
  A->>A: regex-parse IOCs / MITRE / hashes
  A-->>U: report + streamed events
  U->>A: POST /chat (question)
  A-->>U: Cortex/SQLite retrieval → Claude answer

Fig. 2 — The scripted agent run. Deobfuscation and decompilation only — the sample is never executed.

Design decisions & the trade-offs behind them

Agent-with-tools instead of a hardcoded analyzer

The core design bet is to give a capable model a few sharp tools rather than script every analysis branch. Three tools are exposed through an in-process MCP server: sandbox (run bash inside the Docker container), host_analyze (run bash on the host for pefile/ILSpy, which need .NET), and extract_file (copy an artifact out of the container). The agent decides how to use them; the pipeline just sequences the goals.

Why static, not dynamic

Raven never detonates the sample. It defeats obfuscation and decrypts the payload through analysis — stripping the JScript's noise delimiters, base64- and UTF-16LE-decoding the embedded PowerShell, recovering the AES key and IV from the script, decrypting the payload, then decompiling the resulting .NET assembly with ILSpy. Static recovery is slower to build but far safer and more complete here: it reads the malware's real logic instead of hoping it reveals itself at runtime. The reference report is explicit that all findings are static and the malware was never run.

Reporting: legible text, then structured extraction

The agent writes a full free-text findings report. The orchestrator then runs regular expressions over it to pull structured IOCs — IPs, domains, URLs, file paths, SHA-256/MD5 hashes, and MITRE technique IDs — and fills a report object. A few fields are fixed defaults rather than inferred (for example the type defaults to dropper). It is a pragmatic bridge from prose to structure, and §12 notes where it should become a typed schema the agent emits directly.

RAG chat over the findings

Completed findings are chunked and stored. When Snowflake is configured, retrieval uses Cortex similarity search; otherwise it falls back to a local SQLite keyword search, so the chat still works offline. Retrieved chunks become the context for a Claude Sonnet answer that is instructed to use only that context and cite specific IOCs and MITRE IDs.

The input is hostile by definition

Most tools threat-model their users. A malware analyzer must threat-model its input: every sample is actively trying to escape, mislead, or exploit whatever touches it. Two things make Raven's boundaries worth drawing carefully — the agent has host access, and the agent reasons over attacker-controlled content.

%%{init: {'theme':'base','themeVariables':{'background':'#0c0c0e','primaryColor':'#151517','primaryTextColor':'#e6e6e6','primaryBorderColor':'#00ff41','lineColor':'#555','clusterBkg':'#0c0c0e','clusterBorder':'#262626','fontFamily':'JetBrains Mono, monospace','fontSize':'12px','textColor':'#c0c0c0'}}}%%
flowchart LR
  subgraph Z1["Zone: Untrusted sample"]
    M["Uploaded file
(hostile)"]
  end
  subgraph Z2["Zone: Sandbox (Docker)"]
    BOX["bash / python3
against the sample"]
  end
  subgraph Z3["Zone: Host"]
    AG["Claude agent
bypassPermissions"]
    HT["pefile · ILSpy
on decrypted payload"]
    WS[("workspace/")]
  end
  subgraph Z4["Zone: Cloud"]
    AN["Claude API"]
    SN["Snowflake"]
  end
  M ==>|"docker cp"| BOX
  BOX ==>|"TB①  extract payload"| HT
  AG ==>|"TB②  host bash, no gate"| HT
  BOX -.->|"TB③  output steers agent"| AG
  HT --> WS
  AG --> AN
  WS -->|"findings + IOCs"| SN

Fig. 3 — Containment boundaries. TB② and TB③ are the interesting ones for an agentic analyzer.

Running it — and what it assumes

# Backend (port 8001) + frontend (port 3000)
pip install -r requirements.txt   # fastapi, anthropic, claude-agent-sdk, ...
# Set ANTHROPIC_API_KEY (+ optional Snowflake creds) in .env
./start.sh

The reference analysis also assumes external tooling on the machine: Docker with a running container named malware-sandbox, the .NET 8 runtime with ilspycmd for decompilation, and a pre-produced restringer deobfuscation of the sample. The RAG chat needs an Anthropic key; Snowflake is optional and degrades to SQLite.

Where verification stands

Raven was validated the way reverse-engineering usually is: by ground-truth reproduction. Every recovered artifact — the AES key, the C2 credentials, the capability list — was confirmed against the decompiled source, and the report is careful to separate confirmed facts from inference (it flags the malware family as unconfirmed and notes why the .NET imphash is useless for attribution). That analytical discipline is the real test evidence.

The strategy to articulate

What it lacks is an automated harness. The honest plan is a small regression suite that runs the pipeline against a corpus of known samples and asserts on recovered IOCs and hashes; unit tests around the fragile parts (the report's regex extraction, the deobfuscation transforms); and a CI gate. Being able to name that pyramid — and to say the current evidence is manual reproduction, not automation — reads as more senior than claiming coverage that isn't there.

A four-minute live walkthrough

Run against the reference sample so the agent has a known target and the event stream is dense. Drive toward the reveal: a fully-recovered kill chain from a file nobody could read at the start.

• 0:00Show the raw sample: a 4 MB obfuscated JScript — unreadable. "This is what an analyst starts with. Watch the agent take it apart."
• 0:30Hit Analyze. Narrate the streaming event log as tool calls land — sandbox, decode, decrypt — "every line is the agent's actual tool call, not a progress bar."
• 1:30Point out the AES key and IV being recovered and the payload decrypting. "It found the key in the script and decrypted the hidden .NET binary — no execution."
• 2:15Show the ILSpy decompilation step and the grep that surfaces the C2 host, FTP credentials, and capability strings.
• 3:00Open the report: kill chain, both stage hashes, C2 infrastructure, MITRE techniques, capabilities. "All four stages, recovered statically."
• 3:30Chat: ask "what's the C2 and how does it exfiltrate?" Show the grounded answer citing the FTP host and credentials. Close on the honesty note — family unconfirmed, and why.

Ninety seconds, no jargon

The technical explanation

The questions this project invites

Grouped by where the pressure comes from. The answers concede the real limitations on purpose — a malware-analysis panel rewards precision far more than a confident overstatement.

On the analysis

On safety

On the engineering

The honest roadmap

Known limitations, tracked as findings

Documented like any other assessment — each limitation logged as a severity-tagged finding with a fix. This is the path from an award-winning demo toward a general, hardened analyzer.