CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Claude skills package for malware analysis — not a traditional software project. It contains 6 SKILL.md files (1 orchestrator + 5 sub-skills) with supporting references, templates, and scripts that make Claude perform every phase of the malware analysis lifecycle itself (static tooling, evidence parsing, rule authoring, report writing). The only manual step is executing the sample in the analyst's isolated VM. There is no build system; the only tests are the --self-test flags on the Python scripts.

Repository Structure

The root SKILL.md is the orchestrator — the single entry point for all malware analysis. It routes to the 5 sub-skills based on file type and user intent, manages analysis state across phases in analysis_state.md, and supports multi-sample batch workflows. Users don't need to invoke sub-skills directly.

Each sub-skill is a self-contained directory with a SKILL.md (the skill prompt) plus optional references/, assets/, and scripts/ subdirectories:

malware-triage/ — Rapid static assessment, classification, and prioritization. Claude runs scripts/pe_info.py (needs pefile), scripts/hash_calculator.py, strings, and the root scripts/ioc_extract.py; references cover suspicious APIs and the triage checklist.
malware-dynamic-analysis/ — Part A: VM runbook for the analyst (monitoring setup, execution, text-format evidence exports). Part B: Claude parses the evidence with scripts/procmon_summary.py and scripts/sysmon_summary.py plus tshark exports. References cover tool setup, sandbox build, anti-analysis bypass.
scripts/ (repo root) — ioc_extract.py: IOC extraction/defanging used by every phase (--refang, --format csv|json, --self-test).
specialized-file-analyzer/ — Non-PE file analysis: .NET assemblies, Office macros, PDFs, PowerShell/VBS/JS scripts, archives, LNK files, ELF binaries.
detection-engineer/ — Creating Sigma rules (SIEM), Suricata/Snort rules (IDS), hunting queries, IOC defanging, and IOC format conversion (STIX, CSV, OpenIOC).
malware-report-writer/ — Professional report creation with a 12-section template (assets/report_template.md), YARA rule authoring, and quality checklists.

Intended Workflow

The root SKILL.md orchestrator manages this workflow automatically — users describe what they need and the orchestrator routes to the right sub-skill and phase.

Triage all samples first (classify, prioritize)
Dynamic analysis or specialized file analysis for deep investigation
Detection engineering to create actionable rules from findings
Report writing to document everything professionally

Skill Routing (Cross-Skill Boundaries)

These ownership boundaries require reading multiple SKILL.md files to discover:

YARA rules are authored in malware-report-writer, not detection-engineer. Detection-engineer handles Sigma, Suricata, and hunting queries.
Sigma rules for behavioral detection and Suricata rules for network detection both live in detection-engineer.
File type determines skill: use file command output to route — "Mono/.Net assembly", "Microsoft Office Document", "PDF document", "ELF" all go to specialized-file-analyzer; standard PE32/PE64 executables go to malware-triage then malware-dynamic-analysis.
IOC defanging is handled by detection-engineer, but defanged IOCs appear in reports created by malware-report-writer.

Key Conventions

Skills use YAML frontmatter (name, description) for metadata.
All IOCs in reports and rules must be defanged (e.g., hxxp://, [.]com, [@]).
Reports always include all three hash types: MD5, SHA1, SHA256.
Detection rules (YARA, Sigma, Suricata) must be tested before inclusion in reports.
MITRE ATT&CK technique IDs should be tagged in Sigma rules.
Evidence files should be in text-parseable formats (CSV, JSON, TXT) — not raw binary formats (PML, PCAP, EVTX). The dynamic skill has the conversion commands; sysmon_summary.py reads PowerShell JSON/CSV and evtx_dump JSONL; both summary scripts accept UTF-16 (PowerShell default) or UTF-8.
Skills are written as instructions to Claude ("you run", "you read"), not tutorials for a human. New content should keep that voice and mark VM-only steps explicitly.
Sigma rules require unique UUIDs and use SIDs starting at 1000000+ for custom Suricata rules.

MCP Server Integrations

Optional MCP servers can automate manual steps in the workflow. See references/mcp_integrations.md for the full guide. Key integrations: VirusTotal (hash/URL lookups), Threat.Zone (automated sandbox), Threat Intel (abuse.ch/AbuseIPDB/GreyNoise), MISP (IOC sharing), Shodan (infrastructure recon), Volatility (memory forensics).

Architecture Notes

The host machine runs Claude Code with internet access; the analysis VM (REMnux/FlareVM) is network-isolated. Claude runs static tools on the host and analyzes exported evidence; it never executes malware or extracted stages, and never uploads samples without consent.
Every Python script is stdlib-only (except pe_info.py → pefile). ioc_extract.py, procmon_summary.py, and sysmon_summary.py have a --self-test; run them after touching a script.
The references/ subdirectories contain domain knowledge (suspicious API lists, tool setup guides, best practices) that skills reference inline.
assets/report_template.md in malware-report-writer is the canonical 12-section report structure.
references/indicators.md in malware-triage is the primary suspicious API/string/behavioral pattern database.
references/tool_setup.md in malware-dynamic-analysis covers Procmon, Wireshark, System Informer, Sysmon, Regshot, INetSim, and FakeNet-NG configuration.

Plugin Packaging

.claude-plugin/plugin.json declares "skills": ["./"], which registers only the root orchestrator (name: malware-analysis); sub-skills are loaded by path, not auto-registered. .claude-plugin/marketplace.json (gl0bal01-security) makes it installable via /plugin marketplace add gl0bal01/malware-analysis-claude-skills + /plugin install malware-analysis. Validate with claude plugin validate .. Skills must resolve their own files via $CLAUDE_PLUGIN_ROOT (set when running as a plugin) or the skill directory (git-clone install) — the working directory is the user's workspace, never the skill dir. Keep new script references prefixed with the resolved root.

Testing

bash tests/run.sh is the single source of truth that the toolchain works; run it after touching any script. It uses tests/make_pe.py (a benign PE fixture) and tests/fixtures/ (evidence + obfuscated scripts) — never real malware. tests/out/ and .venv/ are gitignored. CI runs the harness on push/PR via .github/workflows/test.yml.

CI/CD

.github/workflows/test.yml — runs tests/run.sh with analysis deps on push and PR.
.github/workflows/mirror.yml — mirrors the repo to Codeberg on push to main and weekly.

7.1 KiB Raw Blame History