<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# Malware Analysis Pipelines — API Reference

## File Hashing

```python
import hashlib
data = open("sample.exe", "rb").read()
hashlib.md5(data).hexdigest()
hashlib.sha256(data).hexdigest()
hashlib.ssdeep(data)  # fuzzy hashing (via ssdeep library)
```

## YARA

```python
import yara

# Compile from file
rules = yara.compile(filepath="/opt/yara/rules/index.yar")

# Compile from string
rules = yara.compile(source='rule test { strings: $a = "malware" condition: $a }')

# Scan file
matches = rules.match("/tmp/sample.exe")
for m in matches:
    print(m.rule, m.tags, m.strings)

# Scan data
matches = rules.match(data=b"\x00malware\x00")
```

## pefile

```python
import pefile

pe = pefile.PE("sample.exe")
pe.FILE_HEADER.Machine          # 0x14c (i386) or 0x8664 (AMD64)
pe.FILE_HEADER.TimeDateStamp    # Unix timestamp
pe.OPTIONAL_HEADER.AddressOfEntryPoint

# Sections
for s in pe.sections:
    print(s.Name, s.get_entropy(), s.SizeOfRawData)

# Imports
for entry in pe.DIRECTORY_ENTRY_IMPORT:
    print(entry.dll)
    for imp in entry.imports:
        print(f"  {imp.name}")

# Exports
for exp in pe.DIRECTORY_ENTRY_EXPORT.symbols:
    print(exp.name, hex(exp.address))
```

## VirusTotal API v3

```bash
# Upload file
curl -X POST "https://www.virustotal.com/api/v3/files" \
  -H "x-apikey: $VT_KEY" --form "file=@sample.exe"

# Get report by hash
curl "https://www.virustotal.com/api/v3/files/{sha256}" -H "x-apikey: $VT_KEY"

# Get behavior report
curl "https://www.virustotal.com/api/v3/files/{sha256}/behaviours" -H "x-apikey: $VT_KEY"
```

## Suspicious PE Indicators

| Indicator | Significance |
|-----------|-------------|
| Section entropy > 7.0 | Likely packed/encrypted |
| UPX/ASPack sections | Known packers |
| No imports | Dynamically resolved (evasion) |
| .rsrc large vs .text | Embedded payload in resources |
| Compile time in future | Timestomped |

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Analysis completed, no detections |
| 1 | YARA matches or suspicious indicators found |
| 2 | Runtime error or invalid sample |
