<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: building-malware-analysis-pipelines
description: >-
  Build automated malware analysis pipelines that perform static analysis,
  dynamic sandboxing, YARA rule matching, PE/ELF header parsing, string
  extraction, and IOC extraction. Integrates with VirusTotal, CAPE Sandbox,
  and produces structured threat intelligence output.
domain: cybersecurity
subdomain: automation-scripting
tags:
  - malware-analysis
  - yara
  - pe-analysis
  - sandbox
  - ioc-extraction
  - virustotal
  - reverse-engineering
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1587.001"]
---

# Building Malware Analysis Pipelines

## Overview

Manual malware triage is slow and inconsistent. This skill covers building
automated analysis pipelines that hash samples, extract static indicators,
match YARA rules, submit to sandboxes, and produce structured IOC reports.
Pipeline output feeds detection engineering and threat intelligence workflows.

Mode: `[MODE: BLUE]` — Defensive analysis with threat intelligence output.

## Prerequisites

| Requirement | Details |
|---|---|
| Python 3.10+ with `yara-python`, `pefile`, `requests` | Required |
| YARA rules repository for signature matching | Required |
| VirusTotal API key for reputation checks | Required |
| CAPE/Cuckoo sandbox for dynamic analysis (optional) | Required |

## Key Concepts

### File Hashing and Metadata

```python
import hashlib
from pathlib import Path

def hash_sample(filepath: str) -> dict:
    """Compute multiple hashes for a malware sample."""
    data = Path(filepath).read_bytes()
    return {
        "filename": Path(filepath).name,
        "size_bytes": len(data),
        "md5": hashlib.md5(data).hexdigest(),
        "sha1": hashlib.sha1(data).hexdigest(),
        "sha256": hashlib.sha256(data).hexdigest(),
    }
```

### YARA Rule Matching

```python
import yara

def scan_with_yara(filepath: str, rules_path: str) -> list[dict]:
    """Scan a file against compiled YARA rules."""
    rules = yara.compile(filepath=rules_path)
    matches = rules.match(filepath)
    return [
        {
            "rule": m.rule,
            "namespace": m.namespace,
            "tags": m.tags,
            "strings": [
                {"offset": s[0], "identifier": s[1], "data": s[2].hex()[:64]}
                for s in m.strings
            ],
        }
        for m in matches
    ]
```

### PE Header Analysis

```python
import pefile

def analyze_pe(filepath: str) -> dict:
    """Parse PE header and extract security-relevant fields."""
    pe = pefile.PE(filepath)
    sections = [
        {
            "name": s.Name.decode().rstrip("\x00"),
            "virtual_size": s.Misc_VirtualSize,
            "raw_size": s.SizeOfRawData,
            "entropy": s.get_entropy(),
        }
        for s in pe.sections
    ]
    imports = {}
    if hasattr(pe, "DIRECTORY_ENTRY_IMPORT"):
        for entry in pe.DIRECTORY_ENTRY_IMPORT:
            dll = entry.dll.decode()
            imports[dll] = [imp.name.decode() for imp in entry.imports if imp.name]

    return {
        "machine": hex(pe.FILE_HEADER.Machine),
        "compile_time": pe.FILE_HEADER.TimeDateStamp,
        "entry_point": hex(pe.OPTIONAL_HEADER.AddressOfEntryPoint),
        "sections": sections,
        "imports": imports,
        "suspicious": [s["name"] for s in sections if s["entropy"] > 7.0],
    }
```

### String Extraction

```python
import re

def extract_strings(filepath: str, min_length: int = 6) -> dict:
    """Extract ASCII and Unicode strings from binary."""
    data = Path(filepath).read_bytes()
    ascii_re = re.compile(rb"[\x20-\x7e]{%d,}" % min_length)
    unicode_re = re.compile(rb"(?:[\x20-\x7e]\x00){%d,}" % min_length)
    ascii_strings = [s.decode() for s in ascii_re.findall(data)]
    unicode_strings = [s.decode("utf-16-le").rstrip("\x00") for s in unicode_re.findall(data)]
    # Extract IOCs
    urls = [s for s in ascii_strings + unicode_strings if re.match(r"https?://", s)]
    ips = [s for s in ascii_strings if re.match(r"\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}", s)]
    return {
        "ascii_count": len(ascii_strings),
        "unicode_count": len(unicode_strings),
        "urls": urls[:50],
        "ips": ips[:50],
    }
```

## Workflow

### Step 1: Hash and Identify Sample

```bash
node scripts/agent.js --action hash --sample /tmp/suspicious.exe
```

### Step 2: YARA Scan

```bash
node scripts/agent.js --action yara-scan --sample /tmp/suspicious.exe --rules /opt/yara/index.yar
```

### Step 3: Static PE Analysis

```bash
node scripts/agent.js --action pe-analyze --sample /tmp/suspicious.exe
```

## Verification

- [ ] Hashing produces MD5, SHA1, SHA256 for every sample
- [ ] YARA matching reports rule name, tags, and matched strings
- [ ] PE analysis extracts imports, sections, and flags high-entropy sections
- [ ] String extraction identifies embedded URLs and IPs
- [ ] Exit code 0 on clean, 1 on detections, 2 on error

## References

- [YARA Documentation](https://yara.readthedocs.io/)
- [pefile Documentation](https://github.com/erocarrera/pefile)
- [VirusTotal API v3](https://docs.virustotal.com/reference/overview)
- [MITRE ATT&CK T1027 — Obfuscated Files](https://attack.mitre.org/techniques/T1027/)
