--- # Malware Analysis Writing Guidelines for AI Assistants # # This file contains two distinct components with different authorship and licensing: # # 1. WRITING GUIDELINES (this file's primary content) # Author: Lenny Zeltser # Copyright (c) 2026 Lenny Zeltser. This copyright covers the guidance in this file; # any content you create using this guidance is entirely yours. # # 2. MALWARE ANALYSIS REPORT TEMPLATE (referenced, not contained here) # Author: Lenny Zeltser # License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/) # Report template: public/media/archive/malware-analysis-report-template.md # # The template license covers the template itself; reports you create are yours. # # This report family has no companion brief by design. See `briefPolicy` for the # reason and for where the decision-maker layer lives instead. # # URL PATHS: All paths starting with `/` are relative to baseUrl. # Example: "/media/archive/file.md" resolves to "https://zeltser.com/media/archive/file.md" # Metadata for this guidelines file title: "Malware Analysis Writing Guidelines" version: "1.1.0" author: "Lenny Zeltser" date: "2026-05-29" license: "Copyright (c) 2026 Lenny Zeltser" baseUrl: "https://zeltser.com" articleUrl: "/malware-analysis-report" # Metadata for the associated Malware Analysis Report Template (separate file, separate license) template: title: "Malware Analysis Report Template" author: "Lenny Zeltser" license: "CC BY 4.0" downloadUrl: "/media/archive/malware-analysis-report-template.md" wordTemplateUrl: "/media/archive/malware-analysis-report-template.docx" # Companion articles that ground the methodology companionArticles: - url: "/malware-analysis-report" title: "A Report Template for Malware Analysis" role: "Introduces the report template and explains how it orders the analysis around the questions defenders ask." # MCP Server Metadata mcp: toolPrefix: "malware" privacyStatement: "This server never requests your sample, your analysis notes, or your indicators, and it instructs your AI to keep them local. The malware tools return guidelines, the report template, and framework references to your AI for local analysis." fallbackUrl: "https://zeltser.com/malware-analysis-report" # Pointers to other capabilities on the same MCP server. The malware # report is intentionally narrow: it analyzes the sample. The decision, # response, attribution, and remediation layers belong to sibling tools. # Each handoff carries a `handoffSignal:` describing when to reach for it. mcpHandoffs: - tool: "ir_load_context" handoffSignal: "When the organization is or may be affected by this sample and someone needs to decide on containment, eradication, recovery, or notification, route to the incident response tools. The malware report supplies the technical facts; the incident response report and brief carry what defenders did and what leaders must decide." - tool: "cti_load_context" handoffSignal: "When the work shifts from the sample to the actor or campaign behind it, such as attribution, victimology across many targets, or tracking a cluster over time, route to the cyber threat intelligence tools. Malware family identification stays in the malware report; threat-actor attribution does not." - tool: "vuln_load_context" handoffSignal: "When the sample reached the environment through a malicious or compromised dependency or product, such as a backdoored open-source package or a supply-chain compromise, and someone needs to decide whether and how fast to remove it, route to the vulnerability tools. That is an exposure-and-remediation decision the Vulnerability Investigation Brief owns." - tool: "assessment_load_context" handoffSignal: "When the sample was found during a security assessment such as a penetration test or red team engagement and the deliverable is a findings-based assessment report, route to the assessment tools for the report and brief structure." - tool: "rating_score_writing" handoffSignal: "When the writer wants a numeric score for the report against the Structure, Words, or Tone rubric, route to this tool. Treat the rating tool as the source of truth for general writing quality." - tool: "rating_get_sheet" handoffSignal: "When the writer wants the rubric itself, without scoring, for self-review, route here. Pair it with the cross-cutting criteria in `crossCuttingCriteria`." - tool: "get_security_writing_guidelines" handoffSignal: "When the writer asks about the Five Elements of cybersecurity writing (Information, Tone, Words, Structure, Look), or about general security-writing tone and structure, route here. Read the general guidance first, then apply this file's malware-specific discipline on top." - tool: "search_zeltser" handoffSignal: "When the writer wants related articles on malware analysis, reverse engineering, incident response, or security leadership, route here to discover the broader Zeltser canon. The companion articles named in this file are a starting point. More exist." # Cross-server handoffs. Tasks an AI agent often needs while analyzing a # sample or writing a malware report that the zeltser-website MCP server # can't perform. Availability depends on the agent's MCP configuration. # Each entry suggests, it doesn't require. crossServerHandoffs: - capability: "Sandbox detonation and dynamic-analysis automation" whenToRoute: "When the writer needs to run the sample in an instrumented environment to populate the Automated Analysis and Behavioral Analysis subsections, or to confirm a behavior they couldn't trigger by hand." suggestedServers: ["A malware sandbox MCP server, self-hosted or commercial"] note: "Availability depends on the agent's installed MCP servers and the writer's access. If none are available, detonate in your own analysis environment and record the configuration in the Analysis Environment appendix. Never submit a sensitive or targeted sample to a public sandbox without authorization." - capability: "Multi-engine reputation and file intelligence" whenToRoute: "When the writer needs antivirus detection names, first-seen dates, prevalence, or related-sample pivots to support the Malware Family Identification, Sources, or Static Properties subsections." suggestedServers: ["A multi-engine file-reputation or sample-intelligence MCP server"] note: "Availability depends on the agent's installed MCP servers and the writer's subscription. If none are available, query the service's portal directly and cite the service and the lookup date. Detection names are a starting point for the family call, not the conclusion." - capability: "Detection-content sources and rule repositories" whenToRoute: "When the writer is drafting the Detection Engineering section and wants existing YARA or Sigma rules to adapt, or wants to cross-check a rule against a corpus." suggestedServers: ["YARA rule repository MCP server", "Sigma rule repository MCP server"] note: "Availability depends on the agent's installed MCP servers. If none are available, retrieve rules from the maintaining project and cite the rule's author and source. Adapt rules to the family or behavior, don't copy a single-hash rule." - capability: "Infrastructure and passive-DNS enrichment" whenToRoute: "When the writer needs registration history, passive DNS, or hosting context to add useful detail to the Context column of a network indicator in the Indicators of Compromise section." suggestedServers: ["Passive-DNS MCP server", "WHOIS or domain-intelligence MCP server"] note: "Availability depends on the agent's installed MCP servers and the writer's access. If none are available, use the provider's portal and cite the lookup date. Defang any indicators that appear in the report." - capability: "Symbol, PDB, and code-signing certificate lookup" whenToRoute: "When the writer is documenting Static Properties or Code Analysis and needs to resolve symbols, check a PDB path, or look up a code-signing certificate's issuer and revocation status." suggestedServers: ["Symbol-server MCP server", "Certificate-transparency MCP server"] note: "Availability depends on the agent's installed MCP servers. If none are available, use the vendor's symbol server or a certificate-transparency search and cite what you accessed." # Scope and limitations scope: "Methodology, frameworks, and writing guidance for malware analysis reports centered on a single sample or a set of related artifacts, such as a dropper plus its payload chain. This guidance analyzes the sample itself: what it is, what it can do, how it arrives, and how confident we are in identifying it." limitation: "This guidance stops at the sample. For what defenders did during an incident, including containment, eradication, and recovery, use the `ir_*` tools. For the actor or campaign behind the sample, including attribution and victimology across many targets, use the `cti_*` tools. For an exposure-and-remediation decision, including a malicious or compromised dependency the organization needs to remove, use the `vuln_*` tools. Malware family identification by code reuse and string overlap stays here; threat-actor attribution does not." # ─── BRIEF POLICY (NO COMPANION BRIEF, BY DESIGN) ───────────────────── # Author-facing guidance for the AI consuming this file, not copy for a # template reader. The malware report has no companion brief. Don't draft # one, and don't tell a reader that one is missing; a reader doesn't # expect a malware brief. When a decision needs a brief, it belongs to a # sibling capability named below. briefPolicy: hasCompanionBrief: false rationale: "A brief exists to help a decision-maker act, and each sibling report describes something an organization must decide about. An incident response report describes an event, so a leader decides on containment and notification. A threat intelligence report describes an adversary, so a leader decides how much to care. A vulnerability investigation describes an exposure, so a leader decides whether and how fast to remediate. A malware analysis report's subject is an object, the sample. What it is, what it can do, how it arrives, and how confident we are in identifying it are inputs to a decision, not a decision on their own, so a brief derived only from the report carries no decision for the reader to make." decisionLayerOwnership: - condition: "The organization is or may be affected" owner: "Incident Response brief and report (`ir_*` tools)" - condition: "The sample ties to a threat actor or campaign the organization tracks" owner: "Cyber Threat Intelligence brief and report (`cti_*` tools)" - condition: "The sample reached the environment through a malicious or compromised dependency or product, including the newsworthy supply-chain case" owner: "Vulnerability Investigation brief (`vuln_*` tools), and Incident Response once a compromise is confirmed" - retainedHere: "Malware family identification by code-reuse and string-overlap lineage stays in the malware report. Threat-actor attribution does not." shareableSummary: "The report's Executive Summary is the shareable skim layer a brief would otherwise provide. Coach the writer to make it stand on its own for a non-analyst, such as a manager deciding whether to escalate, so the report hands off cleanly to whichever sibling owns the decision." authorNote: "This block is guidance for you, the AI. Don't surface 'there is no brief' to a template reader, and don't add a brief section, a brief field, or a brief tool. When the writer asks for a decision-maker one-pager, route to the sibling that owns the decision rather than distilling the malware report into a brief." # ─── APPLICABILITY PROFILES ─────────────────────────────────────────── # Two archetypes seen in real malware reporting. The profile picks which # sections and markings ship in the finished report. Distribution # restriction is expressed by the per-profile TLP marking rather than by a # separate internal-versus-public split, because malware reports vary more # by how formal they are than by who receives them. applicabilityProfiles: - name: "organizational-report" description: "A formal report produced by a team, a security operations center, a CERT, or a vendor research group. Tables carry the facts, sections are explicit, and the report is filed, shared with partners, or published as a vendor advisory. Example: a malware analysis report from an in-house team to its incident responders, or a vendor research write-up published as a formal report." requiredSections: - "Executive Summary" - "Sample Snapshot" - "Malware Family Identification" - "Component Inventory" - "Capabilities" - "Indicators of Compromise" - "Analysis Details" - "About this Report" recommendedSections: - "Runtime Requirements" - "Sources" - "What We Don't Know" - "Appendix: Analysis Environment" situationalSections: - section: "Infection Vector (Optional)" trigger: "The delivery path is known and the report should document how the sample reached the target." - section: "Detection Engineering (Optional)" trigger: "The team is publishing detection logic or hunting guidance alongside the analysis." - section: "Appendix: Analysis Scripts (Optional)" trigger: "The author is sharing config extractors, deobfuscation scripts, or analysis notebooks." markingsThatApply: - "A TLP marking at the top of the report" - "The organization's own data-classification label" rationale: "Formal reports benefit from the full structure. The table-driven sections, the explicit confidence in the family call, and the reproducibility appendices all carry value when the report is filed, shared, or published." - name: "researcher-narrative" description: "An individual researcher's write-up, often a blog post or a thread, that walks through the analysis as a narrative rather than a filed report. Sample Snapshot facts are woven into the prose, the tone is first-person, and classification is usually TLP:CLEAR or absent. Example: a reverse-engineer's blog post detailing how they unpacked and characterized a loader." requiredSections: - "Executive Summary" - "Capabilities" - "Indicators of Compromise" - "Analysis Details" recommendedSections: - "Malware Family Identification" - "What We Don't Know" - "Appendix: Analysis Scripts (Optional)" situationalSections: - section: "Sample Snapshot" trigger: "The author wants a quick-reference table even in a narrative piece. Otherwise the snapshot facts live in the opening prose." - section: "Detection Engineering (Optional)" trigger: "The researcher is sharing a YARA rule or hunting idea, which is common in this format." markingsThatApply: - "TLP:CLEAR, or no marking, since researcher write-ups are usually public" rationale: "Researcher narratives often weave the snapshot facts into prose rather than a formal table, and they tend to lead with the reverse-engineering story. The same content matters, but the format is looser. Coach toward clarity and reproducibility rather than toward filling every table." # ─── FRAMEWORKS ─────────────────────────────────────────────────────── # Every framework named in the template or guidance carries the # attribution below. Direct quotations from primary sources are short and # attributed via each framework's `fullCitation:` and `url:`. The # `primarySourceAccess:` flag records whether the primary source was read # directly (`fetched`) or referenced via a secondary source (`secondary`). # Don't present any framework's wording, or any other analyst's wording, # as original. Cite it. # # MBC and the capability model are unique to malware and carry full # treatment here. Frameworks shared with the CTI report (ATT&CK, Pyramid # of Pain, ICD-203, STIX, TLP) are named with their malware-specific role # only and hand off to `cti_get_guidelines` for the canonical citation, # so this file doesn't replicate sibling content. frameworks: - name: "Malware Behavior Catalog (MBC)" publisher: "The MBC Project (MITRE Corporation, with community contributors)" url: "https://github.com/MBCProject/mbc-markdown" primarySourceAccess: "fetched" primarySourceQuote: "The Malware Behavior Catalog (MBC) is a catalog of malware objectives and behaviors, created to support malware analysis-oriented use cases, such as labeling, similarity analysis, and standardized reporting." role: "The primary vocabulary for the Capabilities section. MBC characterizes what a sample does in malware-analysis terms, organized into Objectives (the high-level categories) and Behaviors (the specifics under them)." objectivesVerbatim: - "Anti-Behavioral Analysis" - "Anti-Static Analysis" - "Collection" - "Command and Control" - "Credential Access" - "Defense Evasion" - "Discovery" - "Execution" - "Exfiltration" - "Impact" - "Lateral Movement" - "Persistence" - "Privilege Escalation" relationshipToAttack: "MBC builds on MITRE ATT&CK and, by design, doesn't duplicate it. Many MBC objectives share names with ATT&CK tactics, and Anti-Behavioral Analysis and Anti-Static Analysis are malware-specific additions. MBC expects you to cite ATT&CK technique IDs for procedures it doesn't carry a behavior for. See `capabilityModel` for how the template applies this." - name: "MITRE ATT&CK" publisher: "The MITRE Corporation" url: "https://attack.mitre.org" branding: "First reference must be 'MITRE ATT&CK®'. Subsequent references can use 'ATT&CK'. Always capitalized, no hyphen, no abbreviation." role: "Two uses in the malware report. In the Capabilities section, ATT&CK is the escape hatch for a procedure that has no fitting MBC behavior; cite the technique ID in the Notes column (see `capabilityModel`). In the Infection Vector section, ATT&CK Initial Access techniques name how the sample reached the target." handoff: "The CTI guidance carries the canonical ATT&CK treatment (version, citation, design philosophy). This file covers only the malware-report use. Call `cti_get_guidelines` or attack.mitre.org for the rest." - name: "Pyramid of Pain" author: "David J. Bianco" url: "https://detect-respond.blogspot.com/2013/03/the-pyramid-of-pain.html" role: "Orders the Indicators of Compromise table by cost to the adversary, so higher tiers are more durable for detection. The malware IOC tiering, including the report's own Cloud Resources addition and the no-loot rule, is in the `pyramidOfPain` block." handoff: "Bianco's original tiers and the fuller treatment are in the CTI guidance. Call `cti_get_guidelines` for the canonical version." - name: "ICD-203 (Analytic Standards)" publisher: "Office of the Director of National Intelligence (ODNI)" url: "https://www.dni.gov/files/documents/ICD/ICD-203.pdf" role: "Provides the confidence vocabulary (high, moderate, low) for the Malware Family Identification section. The malware-specific application is in the `confidence` block. The report does not use the ICD-203 likelihood ladder, since sample analysis is retrospective." handoff: "The CTI and security-writing guidance carry the full ICD-203 treatment, including the confidence-versus-likelihood separation. Call `cti_get_guidelines` for it." - name: "STIX 2.1" publisher: "OASIS Cyber Threat Intelligence Technical Committee" url: "https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html" role: "A machine-readable format for the full indicator set when a consumer needs to ingest it. The IOC section keeps the report's table short and points to a STIX bundle, or a MISP event (https://www.misp-project.org), for the complete set." handoff: "The CTI guidance carries the canonical STIX treatment. Call `cti_get_guidelines` for it." - name: "TLP 2.0 (Traffic Light Protocol)" publisher: "Forum of Incident Response and Security Teams (FIRST)" url: "https://www.first.org/tlp/" role: "The sharing-restriction marking placed at the top of the report and cited in the About this Report classification field. A common choice when sharing a malware report with the security community." handoff: "The CTI and security-writing guidance carry the full TLP treatment, including the label definitions and the four-labels-plus-modifier detail. Call `cti_get_guidelines` for it." # ─── CAPABILITY MODEL (MBC PRIMARY, ATT&CK ESCAPE HATCH) ────────────── # How the Capabilities section characterizes what a sample does. MBC is # the primary vocabulary; ATT&CK is the escape hatch for procedures MBC # doesn't carry a behavior for. The Capabilities section guidance in # `longReportSections` points here rather than repeating the decision tree. capabilityModel: primaryFramework: "Malware Behavior Catalog (MBC)" escapeHatch: "A MITRE ATT&CK technique ID in the Capabilities Notes column, used when no clean MBC behavior fits the observed procedure." objectiveExamples: - "Defense Evasion" - "Discovery" - "Credential Access" - "Collection" - "Command and Control" - "Impact" - "Persistence" - "Anti-Behavioral Analysis" - "Anti-Static Analysis" decisionTree: - condition: "A clean, specific MBC behavior fits the observed procedure." action: "Use the MBC behavior in the MBC Behavior column. Add ATT&CK context in Notes only if it helps the reader." - condition: "No clean MBC behavior fits, but a fitting MBC objective (the broader category) exists." action: "Record the procedure under that MBC objective and cite the relevant ATT&CK technique ID in the Notes column." - condition: "There is no MBC home at all." action: "Place the procedure under the closest MBC objective, cite the ATT&CK technique ID in the Notes column, and mark the note as an ATT&CK gap-fill so the reader sees that row isn't purely MBC." attribution: "MBC is the primary vocabulary, ATT&CK is the escape hatch, and both are cited with attribution. Don't present either framework's wording as original, and don't drop MBC in favor of ATT&CK just because ATT&CK is more familiar. MBC's gaps are known in mobile collection, desktop data collection, and some Windows privilege-escalation procedures, which is exactly where the escape hatch earns its place." dataTargetedCue: "When the sample collects or exfiltrates victim data, name what it targets in the Capabilities prose or an Analysis Details note, such as credentials from local stores, session tokens, SMS or two-factor codes, browser-saved passwords, or wallet data. This is what a reader needs to gauge what was taken or put at risk for a stealer or banker sample. Keep stolen victim data out of the Indicators of Compromise table; see `pyramidOfPain.prohibitions`." examplesNote: "Use synthetic examples when illustrating the model, such as the technique ID T1548.002 for a UAC bypass or T1053.005 for scheduled-task persistence. Don't lift a real sample's mapping from another analyst's report and present it as your own." # ─── CONFIDENCE (ICD-203, SCOPED TO FAMILY IDENTIFICATION) ──────────── # The malware report uses ICD-203 confidence on one judgment: the family # call. It does NOT use the seven-tier likelihood ladder. Sample analysis # is retrospective, so the report rarely makes a forward-looking # probability claim. This is a deliberate divergence from the CTI report, # which carries both confidence and likelihood. confidence: framework: "ICD-203" source: "Office of the Director of National Intelligence, 2 January 2015 (as amended through 2023)" url: "https://www.dni.gov/files/documents/ICD/ICD-203.pdf" primarySourceAccess: "fetched" appliesTo: "Malware family identification. The Malware Family Identification section rates the family call high, moderate, or low. Other sections report what was observed, so they don't carry a separate confidence column." levelsNote: "ICD-203 doesn't define a fixed list of confidence levels. It tells analysts to express confidence based on the logic and evidentiary base behind a judgment. The three-level vocabulary below is the IC-common usage the report adopts, with descriptions written for the family-identification call." levels: - level: "high" description: "Strong, corroborated evidence with little ambiguity, such as a precise match to a published YARA rule plus a distinctive code construct shared with known samples of the family." - level: "moderate" description: "Plausible, credibly sourced evidence that isn't corroborated enough for high, such as a behavioral pattern and partial string overlap that fit the family without a precise code match." - level: "low" description: "Weak or fragmentary evidence that could change with more analysis, such as a single loose string match or a vendor label alone." noNamedFamilyCase: "Many samples map to no named family. When that's the case, attach the confidence to the characterization method rather than to a family name. Rating the basis (a behavioral profile, a code-overlap cluster, a self-assigned label) high or low is valid and common. 'No named family, but high confidence the sample is a credential stealer based on its observed behavior' is a complete, honest result. Don't invent a family name to fill the row." confidenceDrivers: description: "Factors that lower confidence in the family call regardless of how much you observed. More indicators isn't the same as stronger identification." drivers: - factor: "Single-source dependency" explanation: "Only one sandbox run, one vendor verdict, or one rule match stands behind the call. Lower confidence until an independent basis corroborates it." - factor: "Packing or anti-analysis" explanation: "Packing, obfuscation, or anti-analysis defenses limited how much you could observe, so the family-defining code or behavior may be hidden." - factor: "Evidence age" explanation: "The sample predates your current tooling or reference set, so a match to an older family signature may miss a more recent lineage." - factor: "Behavioral coverage gaps" explanation: "You couldn't trigger a code path that would confirm or rule out the family, so you're judging from what executed rather than the full sample." - factor: "Code-reuse ambiguity" explanation: "Shared code can mean a shared author or a shared library, builder, or leaked source. Decide whether the overlap is family lineage or just common tooling before raising confidence." # ─── PYRAMID OF PAIN (IOC TIERING) ──────────────────────────────────── pyramidOfPain: author: "David J. Bianco" year: 2013 url: "https://detect-respond.blogspot.com/2013/03/the-pyramid-of-pain.html" primarySourceAccess: "fetched" principle: "Order indicators by cost to the adversary. Higher tiers are more durable because changing them costs the adversary more." templateAdaptation: note: "Bianco's model orders indicators by cost to the adversary. The report's IOC table keeps that ordering and lists six observable indicator-type tiers. The Cloud Resources tier is the report's own addition for cloud-native samples, not part of Bianco's original. Pick the most informative indicators per tier and leave a tier's row blank when none apply." tiers: - { tier: 1, name: "Hash Values", scope: "Per-file fingerprints such as SHA-256, an imphash for PE files, and a fuzzy hash like ssdeep or TLSH. Trivial for the adversary to change." } - { tier: 2, name: "IP Addresses", scope: "Easy to rotate." } - { tier: 3, name: "Domain Names", scope: "Slightly harder than IPs since domains need registration and payment." } - { tier: 4, name: "Cloud Resources", scope: "Bucket URIs, IAM roles, cloud function IDs, cloud API endpoints. The report's own addition for cloud-native samples, not one of Bianco's tiers." } - { tier: 5, name: "Network Artifacts", scope: "Patterns the sample leaves on the wire, such as user-agent strings, URI patterns, distinctive HTTP headers, and beaconing patterns." } - { tier: 6, name: "Host Artifacts", scope: "Patterns the sample leaves on endpoints, such as registry keys, mutexes, named pipes, service names, and dropped file paths." } prohibitions: - rule: "No Identities tier. Don't add a tier for stolen credentials, session tokens, two-factor or SMS codes, or wallet data. Those are loot the sample collects from victims, not adversary-controlled indicators of the sample. They belong in the Capabilities section and Analysis Details, where you name what the sample targets. Publishing victim secrets in a shareable IOC feed is both a category error and a sensitivity problem." optionalFutureTier: name: "Adversary-Controlled Identifiers (optional, thin evidence)" status: "Not part of the template. Default to omitting it." rule: "Only a genuinely huntable, adversary-controlled identifier could ever warrant a row, such as an attacker-registered package-publisher account or an OAuth application ID the adversary controls. Victim loot never qualifies. Evidence that this tier is needed is thin, so treat it as a possible future addition, not a recommendation, and when in doubt place such an identifier under Cloud Resources or Host Artifacts with a clear Context note." # ─── LONG REPORT SECTION GUIDANCE ───────────────────────────────────── # Thirteen sections plus two appendices. Section names match the report # template exactly. `applicability` is keyed to the two profiles in # `applicabilityProfiles` (organizationalReport, researcherNarrative). longReportSections: - section: "Executive Summary" purpose: "A short paragraph stating what the sample is, how it gets in, and what it does. This is the takeaway for a reader who only reads the summary, so write it to stand on its own when it's handed to a non-analyst, such as a manager deciding whether to escalate. When the audience is a specific organization, add organization-specific context, including significance." applicability: organizationalReport: "required" researcherNarrative: "required" requiredFields: - "executive_summary_paragraph" commonOmissions: - "Summary reads as a feature list ('the sample uses XOR encoding and creates a mutex') instead of stating what the sample is and what it does to a victim." - "Summary written only for analysts, so a manager can't act on it without reading the whole report." - "Family and confidence left out, so the reader doesn't know how firmly the sample is identified." clarifyingQuestions: - "In one sentence, what is this sample and what does it do?" - "If a manager read only this paragraph, would they know enough to decide whether to escalate?" - "What's the family call, and how confident are you in it?" - section: "Sample Snapshot" purpose: "A quick-reference table profiling the sample so a reader can orient in seconds. Each row summarizes a fuller section elsewhere in the report." applicability: organizationalReport: "required" researcherNarrative: "situational" requiredFields: - "family_name" - "key_capabilities" - "target_platform" - "primary_artifact" - "infection_vector_summary" commonOmissions: - "Target Platform left blank for an ecosystem sample, so the reader doesn't know whether this is a Windows binary, an npm package, a browser extension, or a mobile app." - "Primary Artifact given as a bare hash with no role, so the reader can't tell which component the report centers on." - "Snapshot rows that disagree with the fuller sections they summarize." clarifyingQuestions: - "What single artifact does this report center on, and how is it best identified (a SHA-256, or an ecosystem identifier like a package name and version)?" - "Where does the sample run, an operating system or an ecosystem such as browser extensions or npm packages?" - "What three or four capabilities most clearly characterize the sample?" fieldNotes: - "Primary Artifact may be an ecosystem identifier rather than a file hash, such as an npm package name and version or a browser-extension marketplace listing. When a file hash isn't the authoritative identifier, use the one the source provides, even an MD5 or SHA-1, and say so." - section: "Malware Family Identification" purpose: "The family you believe the sample belongs to, the evidence behind the call, and your confidence in it. Add rows for alternative possibilities you're weighing. This is the only section that carries a confidence rating, scoped per `confidence`." applicability: organizationalReport: "required" researcherNarrative: "recommended" requiredFields: - "family_name" - "family_basis" - "family_confidence" fieldNotes: - "Basis is the evidence type, such as a YARA rule match, string overlap, code reuse, a behavioral pattern, or a vendor detection name." - "Confidence is high, moderate, or low, per `confidence`. When there's no named family, rate the characterization method instead (see `confidence.noNamedFamilyCase`)." - "Family lineage by code reuse or string overlap stays here. Threat-actor attribution does not; that's a `cti_*` job. Code shared with a known actor's tool is a family-lineage observation, not an attribution claim." commonOmissions: - "Confidence omitted, so the family call reads as settled when it isn't." - "A vendor detection name treated as the family conclusion rather than as one basis among several." - "Code reuse with a known actor's tool written as an attribution claim instead of a lineage observation." clarifyingQuestions: - "What family do you believe this is, and what evidence supports the call?" - "How confident are you (high, moderate, or low), and what would raise or lower that?" - "Is the shared code genuine family lineage, or just a common library, builder, or leaked source?" - section: "Component Inventory" purpose: "Each file or artifact in the sample, one per row, with its role. A single-file sample has one row. The Indicators of Compromise section carries per-component hashes, labeled by role." applicability: organizationalReport: "required" researcherNarrative: "situational" requiredFields: - "component_role" - "component_file_name" - "component_file_type" - "component_notes" versionChainGuidance: "When the sample's identity is a version chain rather than a set of files, such as a package that turned malicious in a specific release, record the relevant versions by role, for example the last clean version and the first malicious one. A row may lack a file name or hash, such as an in-memory stage or a package identified only by name and version. Fill what you have and leave the rest blank rather than dropping the row." fieldNotes: - "For a multi-component sample, add a short paragraph or numbered list below the table describing how the components flow into each other, such as a stage 1 dropper that extracts a stage 2 script." commonOmissions: - "A row dropped because it lacked a hash, when an in-memory stage or a named package still belongs in the inventory." - "A version-chain sample forced into a file-per-row table, losing the last-clean and first-malicious versions that matter." clarifyingQuestions: - "How many distinct artifacts make up this sample, and what's each one's role?" - "If the sample is a package or an evolving product, what are the last clean and first malicious versions?" - section: "Runtime Requirements" purpose: "What the sample needs to run. This is the section that best fits ecosystem samples, so use it to capture the affordances a package, extension, or mobile app depends on." applicability: organizationalReport: "recommended" researcherNarrative: "situational" requiredFields: - "runtime_requirements" fieldNotes: - "For an OS-targeted sample, examples include required DLLs, configuration files, registry keys, network resources, and runtime versions." - "For an ecosystem-targeted sample, examples include required permissions, manifest declarations, host-application versions, marketplace identifiers, and abused APIs. A mobile app might declare SMS and accessibility permissions; a browser extension might declare host permissions and a marketplace listing ID; an npm package might require a postinstall script." - "Distinguish dependencies the sample bundles from those it expects to find on the target system." - "For a native executable, the CPU architecture, endianness, and whether it's statically or dynamically linked are part of what it needs to run. A statically linked big-endian MIPS binary, for example, suggests an embedded or IoT target rather than a desktop." commonOmissions: - "An ecosystem sample's permissions and manifest declarations left out, so the reader can't see what the sample was allowed to do." clarifyingQuestions: - "What does the sample need in place to run, and what does it bring with it versus expect on the target?" - "For an ecosystem sample, what permissions, manifest declarations, or APIs does it rely on?" - section: "Sources" purpose: "Where the sample and supporting data came from. Records provenance and any chain-of-custody detail." applicability: organizationalReport: "recommended" researcherNarrative: "situational" requiredFields: - "sample_sources" fieldNotes: - "Sources include internal telemetry, third-party sharing, OSINT, and partner-shared samples. Common OSINT sources include VirusTotal, passive-DNS lookup services, and shared threat-intelligence platforms." - "If a source named a threat actor, that context can appear here, but it stays context. Actor attribution itself is a `cti_*` job." commonOmissions: - "First-observed date and provenance left out, so a reader can't judge how current or how trustworthy the sample set is." - section: "Capabilities" purpose: "What the sample does, characterized with the Malware Behavior Catalog. Above the table, write a brief prose summary of the sample's top-level MBC objectives. In the table, pick the behaviors that most clearly characterize the sample. The decision tree for MBC versus ATT&CK lives in `capabilityModel`." applicability: organizationalReport: "required" researcherNarrative: "required" capabilityModelRef: true requiredFields: - "capability_objective_summary" - "mbc_behavior" - "procedure_observed" - "capability_notes" fieldNotes: - "Apply `capabilityModel`: a clean MBC behavior wins; with no clean behavior but a fitting objective, record the objective and cite an ATT&CK technique in Notes; with no MBC home, use the closest objective, cite the ATT&CK technique, and mark the note as an ATT&CK gap-fill." - "If the sample collects or exfiltrates victim data, name what it targets, per `capabilityModel.dataTargetedCue`. Keep that data out of the IOC table." commonOmissions: - "A flat list of ATT&CK technique IDs with no MBC framing, dropping the malware-analysis vocabulary the section is built on." - "Stolen victim data listed as an indicator instead of named as what the sample targets." - "No prose summary above the table, so a reader has to reverse-engineer the sample's purpose from individual behaviors." clarifyingQuestions: - "In a sentence or two, what are the sample's main objectives in MBC terms?" - "For each notable procedure, is there a clean MBC behavior, or do you need an ATT&CK technique ID in Notes?" - "If the sample steals data, what exactly does it target?" - section: "Indicators of Compromise" purpose: "A table of indicators tiered by the Pyramid of Pain, from lowest to highest cost to the adversary. Pick the most informative indicators per tier and leave a tier blank when none apply. Supply the full set separately, such as a STIX bundle or a MISP event, when a consumer needs to ingest it." applicability: organizationalReport: "required" researcherNarrative: "required" requiredFields: - "ioc_type" - "ioc_indicator" - "ioc_context" defangRule: "Defang URLs and bracket the dots in domains and IP addresses, such as hxxps://examplebot-c2[.]example[.]com and 192.0.2[.]10, so nothing in the report is clickable or resolvable." noLootProhibition: "Stolen credentials, tokens, two-factor codes, and wallet data are loot, not indicators. They go in Capabilities and Analysis Details, never in this table. See `pyramidOfPain.prohibitions`." fieldNotes: - "Use the Context column for each indicator's role and any useful detail, such as command-and-control server, drop site, persistence artifact, or exfiltration host. Keep role descriptions consistent with the Capabilities section." - "For a multi-component sample, give each component its own Hash Values row and name its role from the Component Inventory in the Context column." commonOmissions: - "Indicators presented as a flat list instead of organized by tier, losing the cost-to-adversary signal." - "Context column left empty, so a consumer can't tell what an indicator's role was." - "Victim loot placed in the table (see the no-loot rule)." - "Strings that only matched an indicator pattern, pulled from packed or encrypted bytes, listed as indicators with no evidence the sample uses them." clarifyingQuestions: - "Which tier does each indicator sit at, and what was its role in the sample's activity?" - "Are you defanging every URL, domain, and IP?" - "Is anything in the table actually stolen victim data that belongs in Capabilities instead?" - "Does the sample resolve, contact, drop, or write each indicator, or did it just match a pattern in packed or encrypted bytes?" - section: "Analysis Details" purpose: "The supporting evidence behind the Executive Summary and Capabilities sections. Most readers skim it; analysts validating or building on the work read it closely. Keep a subsection you didn't perform and add a note that it wasn't performed, which usually serves the reader better than removing it." applicability: organizationalReport: "required" researcherNarrative: "required" fieldNotes: - "For a multi-component sample, organize each subsection by component using subheadings that match the roles in the Component Inventory." subsections: - name: "Automated Analysis" purpose: "What automated tooling surfaced, such as a sandbox detonation, and which tools were used. These findings may orient the deeper analysis or account for much of it. For a curated list of public sandboxes and services, point to the Free Automated Malware Analysis Sandboxes and Services article rather than naming tools that change over time. When an automated agent or an MCP-driven toolkit produced these findings, name the tool and the analysis depth it ran, so a reader can weigh and reproduce them." requiredFields: - "automated_analysis" - name: "Static Properties Analysis" purpose: "The static properties worth calling out and what each tells you, rather than every field. Property examples include entry point, packing or obfuscation, file or section entropy, codesigning status, key strings, embedded resources, imports and risky API patterns, exports, section hashes, and compile timestamp. Significance explains why each matters, such as high entropy suggesting packing, a PDB path revealing a possible attribution detail, or an imphash matching a known family. If the sample is packed or encrypted, say so and name the packer when you can, then state whether these properties describe the packed form or an unpacked one you produced." requiredFields: - "static_property" - "static_significance" - name: "Behavioral Analysis" purpose: "What the sample does when executed in a controlled environment, covering file system, registry, process, and network activity, persistence, and privilege escalation. Cite the observation behind each claim." requiredFields: - "behavioral_analysis" - name: "Memory Analysis" purpose: "Findings from memory forensics, such as rogue processes, injected or hollowed code, API hooks, unpacked payloads recovered from memory, and in-memory configuration or strings. Note the capture method and tools." requiredFields: - "memory_analysis" - name: "Code Analysis" purpose: "Code-level findings from static disassembly, decompilation, emulation, and dynamic debugging. Reference instruction addresses or function names so other analysts can replicate the work." requiredFields: - "code_analysis" commonOmissions: - "A subsection silently dropped instead of kept with a not-performed note, so a reader can't tell whether the analysis was skipped or just turned up nothing." - "Claims in Behavioral or Code Analysis without the observation that supports them." - "Findings reported without saying whether they came from the packed or the unpacked form, when a packed or encrypted sample makes the two differ." - section: "What We Don't Know" purpose: "What you couldn't resolve, trigger, or verify, and the source or methodology limitations behind those unknowns. Naming the gaps is the discipline that separates mature analysis from confident-sounding guesswork, and it tells the reader when to expect more." applicability: organizationalReport: "recommended" researcherNarrative: "recommended" requiredFields: - "analysis_gaps" fieldNotes: - "Examples include an inability to detonate in a representative environment, missing command-and-control telemetry, restricted access to the original delivery context, a behavior you couldn't trigger, a destructive-impact you couldn't safely confirm, or version-coverage gaps for an evolving package." commonOmissions: - "Section absent, leaving the reader to assume the analysis is more complete than it is." - "Gaps stated abstractly ('limited visibility') instead of specifically ('couldn't trigger the ransomware's file-encryption branch without a live C2 response')." clarifyingQuestions: - "What couldn't you resolve, trigger, or verify?" - "What evidence would change your read of the sample?" - section: "Infection Vector (Optional)" purpose: "How the sample reached the target, if known, referencing MITRE ATT&CK Initial Access techniques where they apply. Write it as a narrative paragraph or a numbered list." applicability: organizationalReport: "situational" researcherNarrative: "situational" triggers: - "The delivery path is known well enough to document." requiredFields: - "infection_vector_narrative" fieldNotes: - "Examples include a phishing attachment, a drive-by download, a supply-chain compromise, removable media, and an exploit kit. Note the attack chain that preceded installation when the data shows it. Include the specific distribution URL or source path when known, defanged, such as a direct download link, a watering-hole site, or an app-store listing." commonOmissions: - "Delivery asserted without evidence, when the report only ever observed the sample post-installation." - section: "Detection Engineering (Optional)" purpose: "Detection logic that generalizes beyond the atomic indicators in the IOC section, such as a YARA rule keyed to code or string patterns that catches the family rather than a single hash. Behavioral hunting guidance belongs here too. Include a link to where the rule code is stored." applicability: organizationalReport: "situational" researcherNarrative: "situational" triggers: - "The author is publishing detection logic or hunting guidance." requiredFields: - "detection_content" - "detection_notes" fieldNotes: - "Detection Content may be a finished rule (YARA, Sigma, or an EDR rule) or hunting and monitoring guidance, such as the combination of artifacts or activity to watch for. Behavioral hunting guidance is welcome here, not just finished rules." - "Sigma and other SIEM or EDR rules are optional, since they depend on the log sources where they run and are often better written by the team that runs those tools. Use the Notes column for log-source dependencies, false-positive characteristics, and per-row context." commonOmissions: - "A single-hash detection that the IOC section already covers, instead of a rule that catches the family." - section: "About this Report" purpose: "The metadata block: title, authorship, publication date, classification, follow-up contact, and a changelog." applicability: organizationalReport: "required" researcherNarrative: "recommended" requiredFields: - "report_title" - "authors_and_organization" - "publication_date" - "report_classification" - "follow_up_contact" situationalFields: - field: "TLP marking at the top of the report" situation: "Apply a TLP marking, or the organization's classification label, before the report is shared, so the sharing restriction is visible before the report is read. Public researcher write-ups are usually TLP:CLEAR or unmarked." subsections: - name: "Report Changelog" purpose: "Date, author, and change-description rows tracking edits across versions." requiredFields: - "changelog_entries" commonOmissions: - "No classification or TLP marking on a report that's about to be shared." - "Follow-up contact omitted, so a reader with questions has nowhere to go." - section: "Appendix: Analysis Environment" purpose: "The environment the analysis was conducted in, so other analysts can replicate the work. A best-practice entry point even when most sources don't mention it." applicability: organizationalReport: "recommended" researcherNarrative: "recommended" requiredFields: - "analysis_environment" fieldNotes: - "Cover the analysis distro and version, the sandbox configuration, the network isolation setup, and relevant tool versions. Note any environment-specific assumptions that affect the findings, since they explain why another analyst's results might differ. For a worked walkthrough of assembling a toolkit from free tools, point to the 5 Steps to Building a Malware Analysis Toolkit article rather than enumerating tools that change over time." - "If an automated or agentic tool drove the analysis, such as an MCP server orchestrating a toolkit, record the tool, its version, and the analysis depth alongside the distro and isolation setup." commonOmissions: - "Tool versions and isolation setup left out, so a reader can't tell whether a behavior depended on the environment." - section: "Appendix: Analysis Scripts (Optional)" purpose: "The scripts you wrote or used to analyze the sample and reproduce the findings, such as config extractors, deobfuscation or unpacking scripts, and analysis notebooks. Point to where they're stored. Omit the appendix if you won't be sharing scripts." applicability: organizationalReport: "situational" researcherNarrative: "recommended" triggers: - "The author is sharing reproducibility scripts." requiredFields: - "analysis_scripts_link" fieldNotes: - "Researcher narratives often ship a config extractor or an unpacking script. Link to a repository or a separate file rather than pasting long scripts into the report body." # ─── REQUIRED FIELDS (FLAT) ──────────────────────────────────────────── # A flat list of field IDs used across the report. Each ID may have an # entry in `fieldGuidance` below. Fields without one rely on the # template's own guidance and the per-section guidance above. requiredFields: - "executive_summary_paragraph" - "family_name" - "family_basis" - "family_confidence" - "key_capabilities" - "target_platform" - "primary_artifact" - "infection_vector_summary" - "component_role" - "component_file_name" - "component_file_type" - "component_notes" - "runtime_requirements" - "sample_sources" - "capability_objective_summary" - "mbc_behavior" - "procedure_observed" - "capability_notes" - "ioc_type" - "ioc_indicator" - "ioc_context" - "automated_analysis" - "static_property" - "static_significance" - "behavioral_analysis" - "memory_analysis" - "code_analysis" - "analysis_gaps" - "infection_vector_narrative" - "detection_content" - "detection_notes" - "report_title" - "authors_and_organization" - "publication_date" - "report_classification" - "follow_up_contact" - "changelog_entries" - "analysis_environment" - "analysis_scripts_link" # ─── FIELD GUIDANCE ──────────────────────────────────────────────────── # Semantic indicators, common problems, and worked good/poor examples for # the load-bearing fields. Every example is synthetic. IP addresses use # the RFC 5737 documentation ranges, domains use the RFC 2606 example.com # range, and family names are invented (Win32/Examplebot). No example is # lifted from a real sample or another analyst's report. fieldGuidance: executive_summary_paragraph: semantic_indicators: ["what the sample is", "main takeaway", "stands alone for a manager"] common_problems: - "Reads as a list of techniques instead of what the sample is and does." - "Written for analysts only, so a non-analyst can't act on it." exampleGood: "Examplebot is a Windows credential stealer delivered as a phishing attachment. Once run, it harvests browser-saved passwords and session cookies and sends them to an attacker-controlled server. We identify it as the Examplebot family with high confidence. An infected host should be treated as having exposed any credentials stored in its browsers." examplePoor: "The sample is a packed PE32 executable that creates a mutex, writes to the Run key, and performs XOR-encoded network communication." family_name: semantic_indicators: ["family", "established name", "variant"] common_problems: - "A vendor detection name treated as the family conclusion rather than as one basis." - "An invented family name used to fill the row when the sample maps to no established family." exampleGood: "Examplebot, the name this stealer is already tracked under, matched by a published YARA rule and a shared C2 protocol seen in prior Examplebot samples." examplePoor: "Generic.Malware.Detected" examplePoorWhyWrong: "A scanner's generic verdict is a basis to weigh, not a family identification. If no established family fits, say so and rate the characterization method instead." family_confidence: semantic_indicators: ["high / moderate / low", "ICD-203", "scoped to the family call"] common_problems: - "Confidence omitted, so the call reads as settled." - "Confidence raised on code reuse that's actually a shared library or builder." exampleGood: "High. A published YARA rule matches, and the sample shares Examplebot's distinctive XOR-keyed configuration block seen in prior samples." examplePoor: "Confirmed Examplebot." examplePoorWhyWrong: "'Confirmed' isn't an ICD-203 level and hides how strong the evidence is. Use high, moderate, or low and name the basis." target_platform: semantic_indicators: ["OS", "ecosystem", "where it runs"] common_problems: - "Left blank for an ecosystem sample, so the reader can't tell what kind of artifact this is." exampleGood: "Chromium browser extension (Manifest V3), distributed through a web-store listing." examplePoor: "Windows." examplePoorWhyWrong: "Fine for a Windows binary, but for a package, extension, or mobile app, name the ecosystem so the reader knows what's at risk." primary_artifact: semantic_indicators: ["the artifact the report centers on", "authoritative identifier"] common_problems: - "A bare hash with no role, so the reader can't place it." - "A file hash forced onto an ecosystem sample whose authoritative identifier is a package name and version." exampleGood: "Loader (the dropper's role from Component Inventory), SHA-256 0000...synthetic...0000. Or, for a package: example-malicious-pkg@1.4.2 from the public registry." examplePoor: "abcd1234" mbc_behavior: semantic_indicators: ["MBC behavior", "MBC objective", "ATT&CK escape hatch"] common_problems: - "An ATT&CK technique used where a clean MBC behavior exists." - "A procedure with no MBC home left out instead of recorded under the closest objective with an ATT&CK note." exampleGood: "Credential Access::Credentials from Browser. Notes: harvests saved passwords from Chromium-based browsers. (For a procedure MBC doesn't carry, e.g., scheduled-task persistence, record it under Persistence and note 'ATT&CK gap-fill, T1053.005'.)" examplePoor: "T1555 (credentials from password stores)." examplePoorWhyWrong: "MBC is the primary vocabulary. Lead with the MBC behavior and reserve the ATT&CK technique ID for the Notes column when MBC has no fitting behavior." ioc_type: semantic_indicators: ["Pyramid of Pain tier", "indicator type", "defanged"] common_problems: - "Indicators flattened to a single list instead of organized by tier." - "Stolen victim data placed in the table instead of in Capabilities." - "Indicators left undefanged." exampleGood: "Domain Names | examplebot-c2[.]example[.]com | command-and-control server, contacted every 60 seconds." examplePoor: "https://examplebot-c2.example.com (C2)" examplePoorWhyWrong: "Undefanged and untiered. Bracket the dots, place it in the Domain Names row, and put the role in the Context column." data_targeted: semantic_indicators: ["what the sample steals", "loot", "Capabilities not IOCs"] common_problems: - "Stolen data listed as indicators." - "What the sample takes left vague, so a reader can't gauge exposure." exampleGood: "The sample targets browser-saved credentials, session cookies, and any cryptocurrency wallet files it finds under the user profile." examplePoor: "Steals sensitive data." analysis_gaps: semantic_indicators: ["what you couldn't resolve", "limitation", "what would change the read"] common_problems: - "Section absent, so the analysis looks more complete than it is." - "Gaps stated abstractly instead of naming the specific evidence that's missing." exampleGood: "We couldn't trigger the sample's second-stage download because the command-and-control server was offline during analysis, so the final payload's capabilities are unconfirmed." examplePoor: "Some aspects of the sample were not fully analyzed." detection_content: semantic_indicators: ["YARA", "Sigma", "hunting guidance", "generalizes beyond a hash"] common_problems: - "A single-hash rule that the IOC section already covers." - "A rule pasted in full with no link to where it's maintained." exampleGood: "A YARA rule keyed to Examplebot's XOR-keyed configuration parsing routine, which catches the family across recompiles. Stored at the link below. Notes: low false-positive risk; matches the config stub, not the packer." examplePoor: "rule detects SHA-256 0000...synthetic...0000." # ─── CLARIFYING QUESTIONS ───────────────────────────────────────────── # Questions the AI asks the writer when a field is missing or thin. Keyed # by field or concept. Section-level questions live in # `longReportSections[].clarifyingQuestions`. Surface both when both apply. clarifyingQuestions: executive_summary_paragraph: - "In one or two sentences, what is this sample and what does it do to a victim?" - "Would a manager who reads only this paragraph know enough to decide whether to escalate?" family_name: - "What family do you believe this is, and what's the strongest evidence for the call?" - "If no family fits, what behavioral or code-overlap characterization can you stand behind instead?" family_confidence: - "Is the family call high, moderate, or low confidence, and what would move it?" - "Is the shared code genuine family lineage, or a common library, builder, or leaked source?" mbc_behavior: - "For each notable procedure, is there a clean MBC behavior, or do you need an ATT&CK technique in Notes?" - "Does any procedure have no MBC home at all, so it needs the closest objective plus an ATT&CK gap-fill note?" ioc_type: - "Which Pyramid of Pain tier does each indicator sit at?" - "Is anything in the table actually stolen victim data that belongs in Capabilities?" analysis_gaps: - "What couldn't you resolve, trigger, or verify, and why?" - "What specific evidence would change your read of the sample?" # ─── WRITING GUIDELINES (MALWARE-SPECIFIC LAYER) ────────────────────── # This block names only what's specific to malware analysis reports. For # the Five Elements of cybersecurity writing, call the # `get_security_writing_guidelines` MCP tool. For the Structure / Words / # Tone rubric, call `rating_get_sheet`. The principles below layer on top. guidelines: fiveElementsHandoff: description: "The Five Elements of cybersecurity writing apply to malware reports: Information (the right substance), Tone (honest and calibrated), Words (clear), Structure (scan-friendly), Look (visually tight). For the elements themselves, call `get_security_writing_guidelines`. This block notes only where malware context shifts how a writer applies them." notesByElement: Information: "Separate what you observed from what you inferred. Name the family confidence and the analysis gaps. Put what the sample steals in Capabilities, not in the IOC table." Tone: "Don't overstate the family call to sound decisive. Rate it high, moderate, or low and name the basis. No fear, uncertainty, and doubt; describe what the sample does and let that carry the weight." Words: "Use MBC behavior names for capabilities and reserve ATT&CK technique IDs for the Notes escape hatch. Use ICD-203 confidence words (high, moderate, low). Always 'MITRE ATT&CK®' on first reference, 'ATT&CK' thereafter." Structure: "Lead the Executive Summary with what the sample is and does, written to stand alone. Use tables for Capabilities, the IOC tiers, and Static Properties. Keep a not-performed subsection rather than deleting it." Look: "Apply the report's classification or TLP marking at the top of every shared copy. Defang every URL, domain, and IP so nothing in the report is clickable or resolvable." malwareSpecificRules: - rule: "Lead with MBC behaviors; reach for an ATT&CK technique ID only when MBC has no fitting behavior, and put it in the Notes column." explanation: "MBC is the malware-analysis vocabulary the Capabilities section is built on. ATT&CK is the escape hatch for procedures MBC doesn't carry, per `capabilityModel`. Defaulting to ATT&CK because it's familiar drops the malware-specific framing." example: bad: "Capabilities: T1547.001 (Registry Run Key), T1055 (Process Injection), T1071 (Application Layer Protocol)." good: "Capabilities: Persistence::Modify Registry (Run key); Defense Evasion::Process Injection. Notes use an ATT&CK technique ID only where MBC has no behavior." - rule: "Confidence applies to the family call, high, moderate, or low. Don't attach a likelihood percentage to the analysis." explanation: "Sample analysis is retrospective. The report rates how firmly the sample is identified, not the probability of a future event. The CTI report's seven-tier likelihood ladder doesn't apply here. See `confidence`." - rule: "Stolen victim data is loot, not an indicator. Name it in Capabilities; keep it out of the IOC table." explanation: "Credentials, tokens, two-factor codes, and wallet data are what the sample takes from victims, not adversary-controlled indicators of the sample. They belong where the reader learns what was put at risk, and publishing them in a shareable IOC feed is a sensitivity problem. See `pyramidOfPain.prohibitions`." example: bad: "IOC, Identities tier: victim VPN credentials admin / S3cret! exfiltrated." good: "Capabilities: the sample harvests VPN credentials from the Windows Credential Manager and exfiltrates them to its C2." - rule: "Family lineage stays in the report; threat-actor attribution hands off to the CTI tools." explanation: "Saying a sample shares code with a known family is a lineage observation the malware report owns. Saying who operates it is attribution, which the `cti_*` tools own. Keep the report about the object, the sample." example: bad: "The shared loader code confirms this is the work of the SilentExample espionage group." good: "The loader reuses Examplebot's configuration-parsing code, placing this sample in the Examplebot lineage. Attribution of the operator is out of scope for this report." - rule: "Defang every URL, domain, and IP, and write file and directory names in plain text." explanation: "Bracket the dots and replace the scheme, such as hxxps://examplebot-c2[.]example[.]com and 192.0.2[.]10, so nothing resolves or is clickable. Filenames and paths read as plain text, not as code." - rule: "Keep a subsection you didn't perform, with a note, rather than deleting it." explanation: "An empty Memory Analysis subsection with 'not performed' tells the reader the analysis was scoped, not that nothing was found. A missing subsection reads as a gap the author didn't notice." - rule: "Don't lift another analyst's wording or a vendor report's prose into your report." explanation: "Learn from other reports, then write your own description of what you observed. Quote and attribute when you genuinely need someone else's words, such as a published rule or a framework definition. Plagiarism risk is real in a field where everyone analyzes the same families." # ─── WRITING ANALYSIS ───────────────────────────────────────────────── # Patterns the AI flags when reviewing a draft. writingAnalysis: jargon: description: "Malware-analysis terms that may need a short definition for a non-analyst reader, such as a manager or a legal reviewer." terms: - { term: "C2", expansion: "Command-and-control (the attacker's remote control point for the malware)" } - { term: "Dropper", expansion: "A component whose job is to deliver and run another payload" } - { term: "Loader", expansion: "A component that loads and runs the next stage, often in memory" } - { term: "Packer", expansion: "Software that compresses or encrypts a sample to hide its code from static analysis" } - { term: "imphash", expansion: "A hash of a PE file's import table, used to group related binaries" } - { term: "IOC", expansion: "Indicator of compromise (technical evidence that a sample was present or active)" } - { term: "RAT", expansion: "Remote access trojan (malware giving an attacker interactive control of a host)" } - { term: "Mutex", expansion: "A named system object malware often uses to avoid running twice on one host" } - { term: "MBC", expansion: "Malware Behavior Catalog (the vocabulary for the Capabilities section)" } - { term: "TLSH / ssdeep", expansion: "Fuzzy hashes that measure similarity between files" } passiveVoice: description: "Passive constructions hide who or what acted. Name the sample or the analyst as the subject." examples: - bad: "The Run key was modified and a payload was written to disk." good: "The loader modified the Run key and wrote the payload to disk." vagueTerms: description: "Replace vague quantifiers and adjectives with specifics." examples: - bad: "The sample is highly sophisticated and contacts several servers." good: "The sample resolves three hardcoded domains and beacons to the first that responds every 60 seconds." sentenceLength: description: "Keep sentences short for readability. Malware reports quote long hashes, technique names, and tool names; restructure when a sentence runs long rather than padding it." rule: "Aim for under 20 words excluding fixed identifiers like hashes and technique names." documentFormatting: description: "Use tables for Capabilities (MBC), the IOC tiers, Static Properties, and the Component Inventory. Reserve prose for the Executive Summary, the Capabilities summary, Behavioral and Code Analysis narrative, and What We Don't Know." # ─── AUDIENCE GUIDANCE ──────────────────────────────────────────────── audienceGuidance: principle: "A malware report reaches more than one reader. Layer the technical detail analysts need with an Executive Summary a non-analyst can act on. The summary is the part a manager or other non-analyst reads, so write it to stand on its own." audienceTypes: - type: "Incident responder" characteristics: - "Wants the IOCs, the persistence and host artifacts, and what the sample steals, fast." - "Will pivot from this report into containment and recovery." terminologyGuidance: "Lead the IOC and Capabilities sections with what a responder can act on. Hand off the response decisions to the incident response tools." - type: "Detection engineer" characteristics: - "Wants behavior-level detail and detection logic that generalizes beyond a hash." - "Cares about log-source dependencies and false-positive characteristics." terminologyGuidance: "Make the Capabilities and Detection Engineering sections carry their weight. Tie hunting guidance to observable behavior." - type: "Fellow analyst or reviewer" characteristics: - "Reads Analysis Details closely to validate or build on the work." - "Values reproducibility, named tools, and the analysis environment." terminologyGuidance: "Use precise MBC and ATT&CK vocabulary. Reference addresses and function names. Fill the Analysis Environment appendix." - type: "Manager or other non-analyst" characteristics: - "Reads the Executive Summary and little else." - "Needs to know what the sample is, what it puts at risk, and whether to escalate." terminologyGuidance: "Write the Executive Summary to stand alone. Translate behavior into impact. Define a term on first use or avoid it." # ─── LENGTH GUIDANCE ────────────────────────────────────────────────── lengthGuidance: report: typical: "Two to ten pages for a single-sample report; longer for a multi-component sample or a deep code-analysis write-up." sectionLengthTargets: executiveSummary: "A short paragraph that stands on its own." sampleSnapshot: "A compact table." capabilities: "A short prose summary plus a focused table; pick the behaviors that characterize the sample rather than every behavior observed." analysisDetails: "The longest section; as long as the evidence needs, organized by subsection or by component." indicatorsOfCompromise: "A focused table; supply the full set separately as STIX or MISP when needed." # ─── VOICE GUIDELINES ───────────────────────────────────────────────── voiceGuidelines: description: "A malware-analysis voice that stays precise about what was observed, honest about the family call, and useful to a defender." doUse: - "Direct, practical language that names what the sample does." - "'such as' (not 'like') for introducing examples." - "A teaching orientation; explain why a property matters, not just that it's present." - "MBC behavior names for capabilities; ATT&CK technique IDs only in the Notes escape hatch." - "ICD-203 confidence words on the family call." - "Active voice with the sample or the analyst as the subject." avoid: - "Fear, uncertainty, and doubt; describe behavior and let it carry the weight." - "Overstating the family call ('this is definitely Examplebot') instead of rating it and naming the basis." - "Threat-actor attribution dressed up as a code-lineage observation." - "Stolen victim data in the IOC table." - "Undefanged indicators or filenames set in code font." tone: - "Professional and precise." - "Confident about observations, calibrated about identification." - "Useful to the defender who will act on the report." examples: - principle: "Rate the family call; don't assert it." bad: "This is Examplebot." good: "We identify this as Examplebot with high confidence, based on a published YARA match and a shared configuration-parsing routine." - principle: "Name what the sample steals in Capabilities, not as an IOC." bad: "IOC: stolen credentials admin / S3cret!" good: "The sample harvests browser-saved credentials and exfiltrates them to its C2." - principle: "Specific over vague." bad: "The sample talks to several servers." good: "The sample beacons to examplebot-c2[.]example[.]com every 60 seconds and falls back to 192.0.2[.]10 if the domain fails to resolve." # ─── REVIEW GUIDANCE ────────────────────────────────────────────────── # For providing constructive critique of an existing malware report draft. # Used by the malware_review_report tool. reviewGuidance: purpose: "Help the author strengthen the report. The goal is improvement, not judgment of the analyst." feedbackStructure: - "Start with what the report does well; identify specific strengths." - "Identify areas for improvement with concrete, actionable suggestions." - "Reference specific sections and quote text when giving feedback." - "Prioritize feedback by impact on the report's usefulness to a defender and on the defensibility of the family call." reviewerMindset: - "You're helping the analyst, not grading them." - "Assume good intent; a gap may reflect a sample that resisted analysis, not carelessness." - "The author may have worked under time pressure, with a packed sample, or without a live command-and-control server." - "Focus on the report's effectiveness for its intended readers." feedbackTone: - "Use collaborative language ('consider', 'you might', 'this could be strengthened by')." - "Avoid judgmental phrases ('you failed to', 'this is wrong', 'obviously')." - "Frame gaps as opportunities ('naming what you couldn't trigger would make the analysis more defensible')." # ─── CROSS-CUTTING CRITERIA ─────────────────────────────────────────── # Pass-fail criteria that apply across the whole report. crossCuttingCriteria: - criterion: "Capabilities use MBC as the primary vocabulary; ATT&CK technique IDs appear only in the Notes escape hatch." rule: "Per `capabilityModel`. MBC characterizes malware behavior; ATT&CK fills the gaps MBC doesn't carry." - criterion: "The family call carries an ICD-203 confidence level (high, moderate, or low), or, with no named family, the characterization method is rated instead." - criterion: "No likelihood percentage or seven-tier ladder is attached to the analysis." rule: "Sample analysis is retrospective. Confidence on the family call is the only calibration." - criterion: "Stolen victim data appears in Capabilities or Analysis Details, never in the IOC table, and there is no Identities IOC tier." - criterion: "Every URL, domain, and IP in the report is defanged." - criterion: "Family lineage stays in the report; threat-actor attribution is handed off, not asserted." - criterion: "A subsection that wasn't performed is kept with a note rather than deleted." - criterion: "MITRE ATT&CK on first reference, ATT&CK thereafter; MBC, ATT&CK, Pyramid of Pain, and ICD-203 are attributed where named." - criterion: "The Executive Summary stands on its own for a non-analyst who reads nothing else." # ─── REVIEW CRITERIA (THEMED) ───────────────────────────────────────── # Theme-to-section mapping routes a failing criterion back to the section # where the AI should focus feedback. Section names match # `longReportSections` so a string-equality lookup works. reviewCriteriaSectionMap: identification: - "Sample Snapshot" - "Malware Family Identification" capabilities: - "Capabilities" indicators: - "Indicators of Compromise" evidence: - "Analysis Details" - "What We Don't Know" ecosystem: - "Sample Snapshot" - "Component Inventory" - "Runtime Requirements" detection: - "Detection Engineering (Optional)" reproducibility: - "Sources" - "Appendix: Analysis Environment" - "Appendix: Analysis Scripts (Optional)" distribution: - "About this Report" reviewCriteria: identification: - criterion: "The family call states a confidence level (high, moderate, or low) following ICD-203, scoped to the family." applicability: "all profiles where a family is named" - criterion: "With no named family, the report rates the characterization method instead of inventing a family name." applicability: "all profiles" - criterion: "Basis names the evidence type (YARA match, string overlap, code reuse, behavioral pattern, vendor detection)." applicability: "all profiles" - criterion: "Code reuse with a known actor's tool is written as family lineage, not as threat-actor attribution." applicability: "all profiles" capabilities: - criterion: "Capabilities use MBC behaviors as the primary vocabulary." applicability: "all profiles" - criterion: "An ATT&CK technique ID appears only where MBC has no fitting behavior, in the Notes column, marked as a gap-fill where there's no MBC home." applicability: "all profiles" - criterion: "For a stealer or banker, the Capabilities prose names what the sample targets or steals." applicability: "all profiles where the sample collects victim data" indicators: - criterion: "Indicators are organized by Pyramid of Pain tier, not presented as a flat list." applicability: "all profiles with IOCs" - criterion: "There is no Identities tier, and stolen victim data is not in the table." applicability: "all profiles" - criterion: "Every URL, domain, and IP is defanged, and the Context column gives each indicator's role." applicability: "all profiles with IOCs" evidence: - criterion: "Claims in Behavioral and Code Analysis are tied to the observation that supports them." applicability: "all profiles" - criterion: "A subsection that wasn't performed is kept with a note rather than deleted." applicability: "organizational-report required; researcher-narrative recommended" - criterion: "What We Don't Know names specific, not abstract, gaps." applicability: "all profiles" ecosystem: - criterion: "For an ecosystem sample, Target Platform names the ecosystem and Runtime Requirements captures permissions, manifest declarations, or abused APIs." applicability: "all profiles where the sample is a package, extension, or mobile app" - criterion: "For a version-chain sample, Component Inventory records the relevant versions (such as last clean and first malicious)." applicability: "all profiles where identity is a version chain" detection: - criterion: "Detection content generalizes beyond a single hash the IOC section already lists, or is clearly framed as hunting guidance." applicability: "wherever Detection Engineering is present" reproducibility: - criterion: "Sources records provenance, and the Analysis Environment appendix names the distro, sandbox, isolation, and tool versions." applicability: "organizational-report recommended; researcher-narrative recommended" distribution: - criterion: "A TLP or organizational classification marking appears at the top of a report that will be shared." applicability: "wherever the report is distributed beyond the author" # ─── ANTI-PATTERNS ──────────────────────────────────────────────────── antiPatterns: - pattern: "Defaulting to ATT&CK technique IDs for the whole Capabilities section." why: "MBC is the malware-analysis vocabulary the section is built on. ATT&CK is the escape hatch for procedures MBC doesn't carry, used in the Notes column. Leading with ATT&CK drops the malware-specific framing." - pattern: "Putting stolen victim data (credentials, tokens, two-factor codes, wallet data) in the IOC table, or adding an Identities tier." why: "That data is loot the sample collects, not an adversary-controlled indicator of the sample. It belongs in Capabilities and Analysis Details, and publishing it in a shareable IOC feed is a sensitivity problem." - pattern: "Attaching a likelihood percentage or a seven-tier probability to the analysis." why: "Sample analysis is retrospective. The report rates confidence in the family call, not the probability of a future event. The seven-tier likelihood ladder is a CTI-report tool, not a malware-report one." - pattern: "Turning a code-lineage observation into a threat-actor attribution." why: "Shared code places a sample in a family lineage. Who operates it is attribution, which the CTI tools own. Keep the malware report about the sample." - pattern: "Stating the family call as settled ('this is X') with no confidence level." why: "Identification is a judgment with a basis. Rate it high, moderate, or low and name the evidence, so a reader knows how firmly the sample is identified." - pattern: "Inventing a family name to fill the row when the sample maps to no named family." why: "Many samples have no family. Say so and rate the characterization method (a behavioral profile or a code-overlap cluster) instead of manufacturing a name." - pattern: "Presenting indicators as a flat list instead of by Pyramid of Pain tier." why: "The tiering carries the cost-to-adversary signal that tells a defender which indicators are durable and which the adversary can change cheaply." - pattern: "Leaving indicators undefanged or setting filenames in code font." why: "Undefanged URLs, domains, and IPs are clickable or resolvable in a report that will be shared. Filenames read as plain text in this house style, not as code." - pattern: "Listing automatically extracted strings as indicators without confirming the sample uses them." why: "An IOC extractor run over packed or encrypted bytes returns pattern matches, not indicators. A string earns a row when the sample resolves, contacts, drops, or writes it. Corroborate before the table. An uncorroborated match belongs in Analysis Details, not the IOC table." - pattern: "Reporting capabilities or static properties from a packed sample without saying it's packed or which form was analyzed." why: "A packed or encrypted sample's imports, strings, and entropy belong to the packer, not the payload. The same property means one thing for the packed form and another once unpacked. Name the packer, say whether unpacking succeeded, and label which form each finding describes." - pattern: "Deleting an analysis subsection you didn't perform." why: "A kept subsection with a 'not performed' note tells the reader the analysis was scoped. A missing one reads as a gap the author overlooked." - pattern: "Dropping an ecosystem sample's permissions and manifest declarations." why: "Runtime Requirements is where a reader learns what a package, extension, or mobile app was allowed to do. Omitting it hides the affordances that made the sample dangerous." - pattern: "Forcing a version-chain sample into a one-file-per-row Component Inventory." why: "When a package turned malicious in a release, the identity is the version chain. Record the relevant versions by role rather than dropping rows that lack a file or hash." - pattern: "Writing the Executive Summary only for analysts." why: "The summary is the layer a non-analyst reads. Write it to stand on its own, so a manager can decide whether to escalate." - pattern: "Reusing another analyst's or a vendor's wording as your own." why: "Plagiarism risk is real when everyone analyzes the same families. Learn from other reports, write your own description of what you observed, and quote with attribution when you genuinely need someone else's words." - pattern: "Adding a containment, eradication, or recovery playbook to the malware report." why: "Response is the incident response template's job. The malware report analyzes the sample and hands the response decision to the `ir_*` tools." # ─── ARTICLE KEY POINTS ─────────────────────────────────────────────── # Actionable guidance drawn from the companion articles. Surface these # when coaching a writer, attributing them to the source via the parent # key. These bullets paraphrase the articles' guidance in original wording. articleKeyPoints: malwareAnalysisReportTemplate: title: "From: A Report Template for Malware Analysis" points: - "A malware analysis is only as useful as the reader's ability to find what matters, so order the report around the questions defenders ask rather than around the order you happened to discover things." - "Lead with what the sample is and does. The Executive Summary is the part most readers read, and the only part some readers read." - "Surface capabilities and indicators of compromise in predictable places, with the supporting analysis behind them for the readers who validate or build on the work." - "Characterize behavior with the Malware Behavior Catalog, and reach for an ATT&CK technique ID when MBC has no fitting behavior for a procedure." - "Name what you don't know. The gaps tell the reader how complete the analysis is and when to expect more." - "The report analyzes the sample. Response, attribution, and remediation decisions belong to the incident response, threat intelligence, and vulnerability artifacts." # ─── RELATED ARTICLES ───────────────────────────────────────────────── relatedArticles: - url: "/malware-analysis-report" title: "A Report Template for Malware Analysis" relevance: "Introduces the report template this YAML supports." - url: "/incident-response-report-template" title: "A Report Template for Incident Response" relevance: "Where the response decision goes once an organization is or may be affected." - url: "/cyber-threat-intel-report-template" title: "A Report Template for Cyber Threat Intelligence" relevance: "Where actor attribution and campaign-level analysis live, beyond the sample." - url: "/vulnerability-management-hamster-wheel" title: "Escaping the Vulnerability Management Hamster Wheel" relevance: "Context-driven significance discipline that informs the exposure-and-remediation decision a malicious dependency raises." - url: "/automated-malware-analysis" title: "Free Automated Malware Analysis Sandboxes and Services" relevance: "A maintained list of public sandboxes and services to point to from the Automated Analysis subsection instead of naming tools that change over time." - url: "/build-malware-analysis-toolkit" title: "5 Steps to Building a Malware Analysis Toolkit Using Free Tools" relevance: "A maintained walkthrough for assembling the analysis environment, for the Analysis Environment appendix." - url: "/cybersecurity-writing-course" title: "SEC402: Cybersecurity Writing — Hack the Reader" relevance: "The SANS course where the underlying writing discipline is taught." # ─── SIBLING ARTIFACTS ──────────────────────────────────────────────── # Pointers to adjacent artifacts so the AI can hand off the decision layer # the malware report deliberately doesn't carry. siblingArtifacts: - name: "Incident Response Report and Brief Templates" purpose: "Responder-facing documentation of what happened during an incident and a decision-maker brief for it. Owns the affected-organization decision the malware report hands off." introducedIn: "/incident-response-report-template" handoffSignal: "Hand off when the organization is or may be affected by the sample and someone needs to decide on containment, eradication, recovery, or notification." - name: "Cyber Threat Intelligence Report and Brief Templates" purpose: "Actor-focused and campaign-focused analysis with a decision-maker brief. Owns the attribution and victimology the malware report leaves out." introducedIn: "/cyber-threat-intel-report-template" handoffSignal: "Hand off when the work shifts from the sample to the actor or campaign behind it, including attribution and tracking a cluster over time." - name: "Vulnerability Investigation Brief Template" purpose: "A decision-maker brief for an exposure-and-remediation decision, including a malicious or compromised dependency the organization needs to remove." downloadUrl: "/media/archive/vulnerability-investigation-brief-template.md" wordTemplateUrl: "/media/archive/vulnerability-investigation-brief-template.docx" introducedIn: "/cyber-brief-templates-for-decision-makers" handoffSignal: "Hand off when the sample reached the environment through a malicious or compromised dependency or product and someone needs to decide whether and how fast to remove it." - name: "Security Assessment Report and Brief Templates" purpose: "Findings-based reporting for penetration tests, vulnerability assessments, red team engagements, and application, infrastructure, and cloud reviews, with risk-adjusted severity and a decision-maker brief." downloadUrl: "/media/archive/security-assessment-report-template.md" introducedIn: "/security-assessment-report-template" handoffSignal: "Hand off when the sample was found during a security assessment and the deliverable is a findings-based assessment report rather than a malware report."