Malspark

Multi-agent malware analysis in which every claim in the report resolves back to the tool call it came from.

Maljan connects LLM agent teams to malware-analysis tools: signature scanners, rule engines, binary and capture readers, a sandbox, an ATT&CK catalogue. The output is a report against MITRE ATT&CK and a STIX 2.1 bundle.

Quick startView on GitHub

Key capabilitiesCopy Anchor Link

• Teams are configuration, not code. A team is an ordered list of stages — triage, the passes the sample is worth, a debate, a verdict and a report — each with a condition, so a team applies to a sample rather than being written for one. See Teams and profiles.
• An evidence ledger with citable ids. Every tool call is written to the ledger as ev_NNNN, and every section of the report names the ids it was built from. See the evidence ledger.
• The agent decides, the code says what is wrong. Nothing rewrites a claim, a technique id, a confidence or an attribution behind the producer's back: a problem goes back to the producer as feedback, with one turn to fix it. See validation loops.
• Format-agnostic routing. The sample's own bytes decide its route (PE, ELF, Mach-O, APK, DEX, documents, scripts, archives); a format nothing recognises gets the neutral path and a report that says so. See format routing.
• Reports that other systems can act on. Markdown, HTML, PDF, the full JSON document, STIX 2.1, an IOC feed with a publish decision on every row, and detection drafts. See Reports and exports.
• Configured from the console. A small bootstrap environment, and every other setting in a store edited from the web console, with setup guides and connection tests. See Configuration.

Multi-agent architecture in briefCopy Anchor Link

A run is one team executing over one sample. The deterministic triage pack establishes the facts first — what the file is, its hashes and signature, what the rule engines and the reputation services say — and writes each to the evidence ledger. The analysts of each stage then call the tools they were given, the debate puts their positions against each other, the judge states the verdict, and the report is assembled from the ledger and the claims that cite it.

The components, the job lifecycle and every stage are described in Architecture.

A quick exampleCopy Anchor Link

Upload a sample and start an analysis with the default team.

TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"..."}' | python -c 'import json,sys; print(json.load(sys.stdin)["access_token"])')

curl -X POST http://localhost:8000/api/v1/samples/upload \
  -H "Authorization: Bearer $TOKEN" -F '[email protected]'

curl -X POST http://localhost:8000/api/v1/jobs \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"sample_id":"<id from the upload>"}'

uv run maljan analyze sample_1 --mock --name test.exe

All documentsCopy Anchor Link

Each document is written against the code in this repository: the bootstrap contract in apps/api/app/bootstrap.py, the settings catalog in src/maljan/core/, the routers under apps/api/app/api/v1/ and the compose stack in docker/.

Images used by these documents and by the top-level README.md live in apps/docs/public/assets/.

Historical design recordCopy Anchor Link

The specs, plans and superpowers notes that once lived under docs/specs/, docs/plans/ and docs/superpowers/ are no longer carried in the working tree; read them with git log -- docs/plans docs/specs docs/superpowers.