---
name: initial-triage
description: >
  Perform rapid triage of suspicious files to determine if they warrant deeper analysis.
  Use when a new sample is received and you need to quickly assess file type, compute
  cryptographic hashes for identification, extract basic metadata, check reputation
  via VirusTotal or other threat intel sources, and decide on next analysis steps.
  Supports both offline (local tools only) and online (API-enriched) modes.
---

# Initial Triage

Quickly assess a suspicious file to determine its nature, compute identifying hashes,
gather basic metadata, and decide whether it requires deeper static, dynamic, or
reverse-engineering analysis.

## Prerequisites

- **Linux**: `file`, `sha256sum`, `md5sum`, `sha1sum`, `strings`, `exiftool` (optional)
- **Windows**: `certutil` (built-in), `Get-FileHash` (PowerShell), `file` (via Git Bash or WSL)
- **Python** (optional, for full automation): `hashlib`, `python-magic`, `requests`
- **VirusTotal API key** (optional, for online reputation lookup): set `VT_API_KEY` env var

## Step-by-Step Instructions

### Step 1: Identify the File Type

Determine the true file type using magic bytes, not the file extension.

**Linux / macOS:**
```bash
file --mime-type suspicious_file
file suspicious_file
```

**Windows (PowerShell):**
```powershell
# Read first 16 bytes to inspect magic bytes manually
$bytes = [System.IO.File]::ReadAllBytes("suspicious_file")[0..15]
($bytes | ForEach-Object { '{0:X2}' -f $_ }) -join ' '
```

**With TrID (cross-platform):**
```bash
trid suspicious_file
```

**With Python script:**
```bash
python3 scripts/triage.py --file suspicious_file --type-only
```

Check the result against known magic bytes. See `references/file-signatures.md` for
a comprehensive list. Common malware carriers:
- `MZ` (0x4D5A) - Windows PE executable
- `\x7fELF` - Linux ELF binary
- `PK` (0x504B) - ZIP archive (also Office .docx/.xlsx, .jar, .apk)
- `%PDF` - PDF document
- `\xD0\xCF\x11\xE0` - OLE2 compound file (legacy Office .doc/.xls)

### Step 2: Compute Cryptographic Hashes

Calculate MD5, SHA1, and SHA256 hashes for identification and lookup.

**Linux / macOS:**
```bash
md5sum suspicious_file
sha1sum suspicious_file
sha256sum suspicious_file
```

**Windows (PowerShell):**
```powershell
Get-FileHash suspicious_file -Algorithm MD5
Get-FileHash suspicious_file -Algorithm SHA1
Get-FileHash suspicious_file -Algorithm SHA256
```

**With Python script:**
```bash
python3 scripts/triage.py --file suspicious_file --hashes-only
```

Record all three hashes. SHA256 is the primary identifier used by most threat
intelligence platforms. MD5 is still widely used in legacy databases.

### Step 3: Check File Size and Basic Properties

Note the file size; anomalies can be informative:
- Very small executables (< 10 KB) may be droppers or downloaders
- Very large files may contain embedded payloads or padding for sandbox evasion
- Files exactly at size boundaries (e.g., 100 MB) may use size-based evasion

**Linux:**
```bash
ls -la suspicious_file
stat suspicious_file
```

**Windows (PowerShell):**
```powershell
Get-Item suspicious_file | Select-Object Name, Length, CreationTime, LastWriteTime
```

### Step 4: Extract Basic Metadata

**Using exiftool (cross-platform):**
```bash
exiftool suspicious_file
```

**For PE files on Linux:**
```bash
python3 -c "import pefile; pe = pefile.PE('suspicious_file'); print(pe.dump_info())" 2>/dev/null | head -50
```

**For Office documents:**
```bash
python3 -c "
from zipfile import ZipFile
with ZipFile('suspicious_file') as z:
    print(z.namelist())
"
```

Look for:
- Original filename vs. submitted filename discrepancies
- Compilation timestamps (future/very old dates are suspicious)
- Internal version info and company names
- Digital signature presence and validity

### Step 5: Lookup on VirusTotal (Online Mode)

If the `VT_API_KEY` environment variable is set, query VirusTotal for the file hash.

**Using the triage script:**
```bash
export VT_API_KEY="your-api-key-here"
python3 scripts/triage.py --file suspicious_file --vt-lookup
```

**Using curl directly:**
```bash
SHA256=$(sha256sum suspicious_file | cut -d' ' -f1)
curl -s -H "x-apikey: $VT_API_KEY" \
  "https://www.virustotal.com/api/v3/files/$SHA256" | python3 -m json.tool
```

See `references/virustotal-api.md` for full API usage, rate limits, and response parsing.

If VirusTotal has no results, consider:
- Uploading the sample (only if authorized and appropriate)
- Checking other platforms: MalwareBazaar, Hybrid Analysis, Any.Run

### Step 6: Check Against Known Malware Signatures

**Using YARA rules (if available):**
```bash
yara -r malware_rules.yar suspicious_file
```

**Quick string-based checks:**
```bash
strings suspicious_file | grep -iE "(CreateRemoteThread|VirtualAllocEx|URLDownloadToFile|WScript\.Shell|powershell|cmd\.exe|/c\s+)"
```

**Check for known packer signatures:**
```bash
strings suspicious_file | grep -iE "(UPX|ASPack|Themida|VMProtect|Enigma)"
```

### Step 7: Generate Triage Report

Run the full triage script to produce a structured JSON report:

```bash
python3 scripts/triage.py --file suspicious_file --output report.json
```

Or use the bash wrapper when Python is unavailable:

```bash
bash scripts/triage.sh suspicious_file
```

### Step 8: Determine Next Analysis Steps

Based on triage findings, decide the analysis path:

| Finding | Recommended Next Step |
|---|---|
| Known malware (VT detection > 50%) | Document, extract IOCs, skip to reporting |
| Packed/obfuscated executable | Static analysis → unpacking → reverse engineering |
| Office document with macros | Static analysis (macro extraction) → sandbox execution |
| Script file (PS1, VBS, JS, BAT) | Static analysis (deobfuscation) |
| PE with low/no detections | Full pipeline: static → dynamic → behavioral → RE |
| ELF binary | Static analysis → sandbox (Linux sandbox or Docker) |
| Unknown file type | Further format analysis, binwalk for embedded files |

## Output Format

The triage script produces a JSON report with the following structure:

```json
{
  "file_name": "sample.exe",
  "file_size": 245760,
  "file_type": "PE32 executable (GUI) Intel 80386, for MS Windows",
  "mime_type": "application/x-dosexec",
  "hashes": {
    "md5": "...",
    "sha1": "...",
    "sha256": "..."
  },
  "metadata": { },
  "virustotal": {
    "detected": true,
    "detections": "45/72",
    "scan_date": "2025-01-15",
    "permalink": "..."
  },
  "quick_indicators": [],
  "recommended_next_steps": []
}
```

## Tips

- Always handle samples in an isolated environment (VM or dedicated analysis machine)
- Never execute suspicious files on your host system during triage
- Document the chain of custody: where the file came from, when it was received
- If working with multiple samples, maintain a sample tracking spreadsheet or database
- Use `ssdeep` for fuzzy hashing to identify similar samples in your collection