ir-narrative
Skill0 starsChanged 6 months agoApache-2.0View on GitHub
Convert structured verified findings into investigative prose suitable for an IR analyst report. Output is a structured narrative, not a raw execution log — required by hackathon rules.
In this repository13 other files it gives its agents.
- accuracy-reportSkill
- containment-recommenderSkill
- evidence-pinSkill
- exec-reportSkill
- gap-acknowledgmentSkill
- linux-triageSkill
- macos-triageSkill
- memory-forensicsSkill
- remediation-plannerSkill
- self-correctSkill
- threat-huntingSkill
- triage-orchestratorSkill
- windows-triageSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
If the event is present, follow this attribution table:
- Very specific: line 22
If the threat_model event is absent, the narrative MUST default to neutral framing: "the active session under user account X performed Y" — …
- Distinctive: line 44
No MITRE codes. No filename jargon.
- Very specific: line 105
Every assertion in prose MUST link back to a finding_id in brackets — [F-042]
- Distinctive: line 106
Use plain language; assume reader is a senior IR analyst not a debugger
- Distinctive: line 108
Do NOT invent intent. "Process X connected to Y" is a fact.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
IR Narrative
Hackathon rules require: "output is presented as a structured investigative narrative, not a raw execution log."
Actor Attribution Rule — READ FIRST (MANDATORY)
Before writing the Executive Summary or Threat Actor Behavior section, check /output/audit.jsonl for the threat_model event written by triage-orchestrator. That event names the actor and the victim. Use it.
If the event is present, follow this attribution table:
threat_model.shape | Actor in narrative | Victim in narrative |
external-physical | "the intruder" or "unauthorized physical actor" — never the local user account name | The local user account; explicitly state they are the victim |
external-remote | "the threat actor" / named malware family / "the compromised credentials operator" | The local user account; explicitly state credentials were compromised |
insider-threat | The local user account name (e.g. "Fred Rocba") | The organization / co-workers / data owners |
If the threat_model event is absent, the narrative MUST default to neutral framing: "the active session under user account X performed Y" — NOT "X (the user) performed Y". Without explicit threat model the agent has not earned the right to attribute intent.
Forbidden framings (categorical failures)
Each of these has shipped a misattributed report before and is now an automatic-reject:
❌ Forbidden in external-* cases | ✅ Correct |
| "This is a textbook insider-threat exfil scenario" | "The 2020-11-13 evening EDT break-in window shows intruder activity through Fred Rocba's logged-in session" |
| "Fred pulled files from co-worker OneDrive folders" | "The intruder, operating through Fred's session, accessed co-worker OneDrive folders" |
| "Disable [victim user]'s tenant account" | "Rotate [victim user]'s session tokens; revoke share links from the compromise window; physical-security review" |
| "Trusted user pulling intellectual-property documents" | "Files accessed via [user]'s session during the compromise window; user was [in Florida / phished / not present] per case brief" |
Timing correlation in attribution
When the threat_model.compromise_window is set, every activity claim in the Threat Actor Behavior section MUST be bracketed against it: "X events occurred inside the compromise window (intruder-attributed) and Y outside (legitimate user activity)." If you cannot recover per-event timestamps for an artifact, say so — do NOT assume "captured in this image = happened during compromise window."
Required Structure
The report has TWO audiences and MUST serve both:
- Plain-English Summary — for someone who is NOT a forensic analyst. No MITRE codes. No filename jargon. No acronyms without spelling out. 3-6 sentences. What happened, who/what was affected, how bad, what action.
- Technical Body — for the IR analyst. MITRE ATT&CK, finding IDs, confidence enums, MACB timestamps, the works.
# Incident Report — Case <CASE_ID>
## What This Means In Plain English
3-6 sentences. NO jargon. NO acronyms (or always spell out on first use).
Think: explaining to the CEO at 2am. "We looked at X. We found Y. Z is
concerning / Z is fine. Do this next."
Then a small table:
| What we looked at | What we found | How sure | What to do |
|---|---|---|---|
| (artifact in plain English) | (1-line plain English claim) | confirmed/probably/unsure | "no action" / "investigate" / "isolate now" |
## Executive Summary
2-3 sentences. Technical-tinged but still readable. What happened,
severity, key actors/targets.
## Timeline of Events
Reverse chronological. Each entry:
- **<timestamp UTC>** — <plain language description> [pin: <finding_id>]
## Threat Actor Behavior
What did they do, in narrative form. Group findings by attacker phase:
- Initial Access
- Execution
- Persistence
- Privilege Escalation
- Defense Evasion
- Credential Access
- Discovery
- Lateral Movement
- Collection
- Command & Control
- Exfiltration
- Impact
(MITRE ATT&CK alignment — only assert TTPs that pin to specific findings.)
## Indicators of Compromise (IOCs)
- File hashes
- IPs / domains
- Process names + cmdlines
- Persistence locations
## Confidence Map
For each section, how certain we are and why.
## Gaps + Recommendations
What we don't know, and what evidence would resolve it.Discipline
- Every assertion in prose MUST link back to a
finding_idin brackets —[F-042] - Use plain language; assume reader is a senior IR analyst not a debugger
- Refer to confidence enum without quoting it: "execution is confirmed by Prefetch and BAM" not "confirmed: yes"
- Do NOT invent intent. "Process X connected to Y" is a fact. "Attacker exfiltrated data via X" is an interpretation; only state it if evidence supports it.
Length
Aim 1-3 pages. Long-form prose loses judges. Tight, evidenced, structured wins.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

