git:20260412.09f91e4 to git:20260905.fd80b2a

8 added, 5 removed. Audit A to A.

# 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 guide Claude through every phase of the malware analysis lifecycle. There is no build system, test suite, or application code.

+ 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 sample assessment, classification, and prioritization (5-30 min per sample). Includes `scripts/hash_calculator.py` and reference files for suspicious API indicators and triage checklists.

- - **malware-dynamic-analysis/** — Safe execution and behavior monitoring in isolated VMs. Covers Procmon, Wireshark, System Informer (formerly Process Hacker), Sysmon setup and evidence collection workflows.

+ - **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.

1. **Triage** all samples first (classify, prioritize)

2. **Dynamic analysis** or **specialized file analysis** for deep investigation

3. **Detection engineering** to create actionable rules from findings

4. **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).

+ - 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 analyzes exported evidence, never executes malware directly.

+ - 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.

## CI/CD

A GitHub Actions workflow (`.github/workflows/mirror.yml`) mirrors the repo to Codeberg on push to `main` and on a weekly schedule.