# Capa Usage Guide

## Overview

[capa](https://github.com/mandiant/capa) is Mandiant's open-source tool for identifying capabilities in executable files. It uses a rule-based system to detect behaviors and maps them to MITRE ATT&CK and the Malware Behavior Catalog (MBC).

## Installation

### Standalone Binary (Recommended)

Download the latest release from GitHub:

```bash
# Linux
wget https://github.com/mandiant/capa/releases/latest/download/capa-linux.zip
unzip capa-linux.zip
sudo install -m 755 capa /usr/local/bin/

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/mandiant/capa/releases/latest/download/capa-windows.zip" -OutFile capa.zip
Expand-Archive capa.zip -DestinationPath "$env:ProgramFiles\capa"
```

### Python Package

```bash
pip install flare-capa
```

### Verify Installation

```bash
capa --version
capa --help
```

## Basic Usage

### Analyze a Single File

```bash
capa sample.exe
```

### JSON Output

```bash
capa --json sample.exe > report.json
capa -j sample.exe | jq '.rules | keys'
```

### Verbose Output (Show Matched Addresses)

```bash
capa -v sample.exe        # verbose
capa -vv sample.exe       # very verbose (shows matched features)
```

### Specify Format

```bash
capa -f pe sample.bin     # Force PE format
capa -f elf sample.bin    # Force ELF format
capa -f sc32 shellcode    # 32-bit shellcode
capa -f sc64 shellcode    # 64-bit shellcode
```

### Use Custom Rules

```bash
capa --rules /path/to/rules/ sample.exe
capa -r ./my-rules/ -r ./community-rules/ sample.exe
```

### Signatures Directory

```bash
capa --signatures /path/to/sigs/ sample.exe
```

## Output Interpretation

### Standard Output Structure

```
+-------------------------------------------+-------------------------------------------+
| ATT&CK Tactic      | ATT&CK Technique                                       |
+-------------------------------------------+-------------------------------------------+
| DEFENSE EVASION     | Obfuscated Files or Information [T1027]                |
|                     | Software Packing [T1027.002]                           |
| DISCOVERY           | System Information Discovery [T1082]                   |
|                     | File and Directory Discovery [T1083]                   |
| EXECUTION           | Native API [T1106]                                     |
+-------------------------------------------+-------------------------------------------+

+-------------------------------------------+-------------------------------------------+
| MBC Objective       | MBC Behavior                                           |
+-------------------------------------------+-------------------------------------------+
| ANTI-BEHAVIORAL     | Virtual Machine Detection [B0009]                      |
| DEFENSE EVASION     | Obfuscated Files or Information::Packing [E1027.002]   |
+-------------------------------------------+-------------------------------------------+

+-------------------------------------------+-------------------------------------------+
| Capability                                | Namespace                                 |
+-------------------------------------------+-------------------------------------------+
| packed with UPX                           | anti-analysis/packer/upx                  |
| receive data                              | communication/socket/receive              |
| create process                            | host-interaction/process/create           |
+-------------------------------------------+-------------------------------------------+
```

### JSON Output Structure

Key fields in JSON output:

```json
{
  "meta": {
    "sample": {
      "md5": "...",
      "sha256": "...",
      "path": "..."
    },
    "analysis": {
      "format": "pe",
      "arch": "i386",
      "os": "windows"
    }
  },
  "rules": {
    "rule name": {
      "meta": {
        "namespace": "...",
        "attack": [...],
        "mbc": [...],
        "authors": [...]
      },
      "matches": {
        "0x401000": {...}
      }
    }
  }
}
```

### Interpreting Results

1. **High-Priority Capabilities**: Focus on capabilities indicating the malware's primary function:
   - `communication/` namespace: Network communication methods
   - `collection/` namespace: Data theft capabilities
   - `impact/` namespace: Destructive capabilities
   - `host-interaction/process/inject`: Code injection

2. **Context Clues**: Combination of capabilities reveals malware type:
   - Keylogging + screenshot + HTTP upload = Info stealer
   - File encryption + ransom note = Ransomware
   - Process injection + HTTP C2 = RAT/backdoor
   - Registry persistence + service creation = Persistent implant

3. **False Positives**: Some capabilities are common in legitimate software:
   - File operations, registry reads, network communication alone are not indicative
   - Look for combinations and anti-analysis techniques

## Common Options Reference

| Flag | Description |
|------|-------------|
| `-j`, `--json` | JSON output |
| `-v` | Verbose (show match locations) |
| `-vv` | Very verbose (show matched features) |
| `-f FORMAT` | Force file format (pe, elf, sc32, sc64, dotnet) |
| `-r PATH` | Custom rules directory |
| `-s PATH` | Custom signatures directory |
| `-t TAG` | Filter rules by tag |
| `--color` | Force colored output |
| `--no-color` | Disable colored output |

## Rule Writing

### Rule Structure

```yaml
rule:
  meta:
    name: rule name
    namespace: category/subcategory
    authors:
      - analyst name
    scope: function
    att&ck:
      - Defense Evasion::Obfuscated Files or Information [T1027]
    mbc:
      - Anti-Behavioral Analysis::Virtual Machine Detection [B0009]
    references:
      - https://example.com
    examples:
      - sha256hash
  features:
    - and:
        - api: CreateRemoteThread
        - api: VirtualAllocEx
        - api: WriteProcessMemory
```

### Feature Types

| Feature | Syntax | Example |
|---------|--------|---------|
| API call | `api: Name` | `api: CreateRemoteThread` |
| String | `string: "text"` | `string: "cmd.exe /c"` |
| Regex | `string: /pattern/` | `string: /https?:\/\//` |
| Bytes | `bytes: HH HH = desc` | `bytes: 4D 5A = MZ header` |
| Number | `number: N` | `number: 0x5A4D` |
| Offset | `offset: N` | `offset: 0x3C` |
| Mnemonic | `mnemonic: name` | `mnemonic: rdtsc` |
| OS | `os: name` | `os: windows` |
| Arch | `arch: name` | `arch: i386` |
| Match | `match: rule` | `match: create process` |
| Count | `count(api(X)): N` | `count(api(Sleep)): 5 or more` |
| Property | `property/read: X` | `property/read: System.Environment.UserName` |

### Logical Operators

```yaml
features:
  # All must match
  - and:
      - api: A
      - api: B

  # Any must match
  - or:
      - api: A
      - api: B

  # Must not match
  - not:
      - api: A

  # N or more must match
  - 2 or more:
      - api: A
      - api: B
      - api: C

  # Optional (match if present, don't fail if absent)
  - optional:
      - api: A
```

### Testing Rules

```bash
# Test a single rule
capa --rules ./my_rule.yml sample.exe

# Test with verbose to see matches
capa -vv --rules ./my_rule.yml sample.exe

# Lint rules
capa-rules-lint ./my_rule.yml
```

## Integration with Other Tools

### With YARA

```bash
# Run capa and YARA together
capa sample.exe > capa_report.txt
yara -r rules/ sample.exe > yara_report.txt
```

### With capa_runner.py

```bash
# Organized report grouped by ATT&CK tactic
python3 capa_runner.py --input sample.exe --format markdown --group-by tactic

# Batch analysis
python3 capa_runner.py --batch /samples/ --output results/ --format csv
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "No rules found" | Check rules path; download default rules from GitHub |
| "Unsupported format" | Use `-f` to specify format explicitly |
| Timeout on large files | Increase timeout; try with `-f` to skip format detection |
| Missing capabilities | Update capa and rules to latest version |
| .NET binary issues | Use `-f dotnet` for .NET assemblies |