AGENTS.md — Using AnalystAIPack as an AI agent

This repository is a skill library for malware analysis, reverse engineering, and threat hunting. If you are an AI coding/security agent, read this file first: it tells you how to find the right skill, run it safely, and chain skills into an investigation.

What this repo is

118 self-contained skills under skills/, one folder each.
Every skill has: SKILL.md (the procedure), scripts/analyst.py (a runnable tool), references/api-reference.md (script docs + sources), and LICENSE.
Machine-readable catalog: index.json. Human catalog: CATALOG.md.

How to pick a skill

Search the catalog by intent, not just keyword:

python tools/analyst-pack.py search <topic>     # e.g. "kerberos", "pe imports", "beacon"
python tools/analyst-pack.py list --subdomain threat-hunting

Read the chosen SKILL.md. Honor its When to Use and especially the **Do not use** line — it states the boundaries of the technique. Do not apply a skill outside its scope.

How to run a skill

Each skill's tool is a small CLI. Inspect it, then run it:

python tools/analyst-pack.py show <skill-name>           # see its subcommands
python tools/analyst-pack.py run  <skill-name> -- <args>  # run it
# or directly:
python skills/<skill-name>/scripts/analyst.py <subcommand> <args>

Scripts print structured JSON. Use that output as input to the next skill or a report.

Safety rules (do not violate)

Never execute the malware sample. Every script performs static, read-only analysis. Do not add code that runs, detonates, or connects to a sample's infrastructure.
Assume an isolated lab. Skills that handle samples include a Safety & Handling section — follow it. Do not move samples out of the working directory.
Keep IOCs defanged in any output you share (hxxp://, 1[.]2[.]3[.]4). The scripts already do this; preserve it.
No live samples in the repo. This project ships none; never commit one (see .gitignore).

Chaining skills (the analyst loop)

A full investigation usually flows: triage → static analysis → unpack/reverse → extract config & IOCs → defang → hunt across telemetry → write a detection. See the worked example in README.md. Pass each script's JSON output forward; defang before sharing.

Framework mapping

Skill frontmatter carries mitre_attack, d3fend, and (for hunts) car IDs. Use these to report coverage and to slot findings into detection engineering. The ATT&CK Navigator layer is at mappings/attack-navigator-layer.json.

If you add or edit a skill

Keep the repo green — run before finishing:

python tools/lint-skills.py --all          # schema + body-section linter
python tools/build-index.py                # regenerate index.json
python tools/build-catalog.py              # regenerate CATALOG.md
python tools/build-navigator-layer.py      # regenerate the ATT&CK layer
python tools/smoke-test.py                 # run every analyst.py (--help + fixtures)

Authoring rules (originality, sourcing, safety) are in CONTRIBUTING.md.

3.3 KiB Raw Blame History