CLAUDE.md git:20260412.09f91e4A

Immutable. This exact content is served forever at /api/v1/blob/8a64bc9c696da727.

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

## 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.
- **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).
- 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 `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.