---
name: sample-acquisition
description: >
  Safely obtain malware samples from repositories and feeds for analysis. Use
  when you need to download malware samples from MalwareBazaar, VirusTotal, or
  other sources, verify sample integrity, handle samples safely, and maintain
  chain of custody documentation.
---

# Sample Acquisition

Safely obtain, verify, and manage malware samples for analysis.

## Prerequisites

- **Python 3.10+** for running downloader and sample manager scripts
- **Isolated analysis environment**: VM or sandboxed system (never handle samples on production machines)
- **7z**: For creating password-protected sample archives
- **API keys** (as needed):
  - `VT_API_KEY` for VirusTotal downloads (premium required)
  - `MALSHARE_API_KEY` for Malshare access
  - `MALWAREBAZAAR_API_KEY` for MalwareBazaar (optional)

## When to Use

- Need to obtain a malware sample by hash, family name, or tag
- Setting up a malware sample collection for research
- Verifying sample integrity after transfer
- Documenting chain of custody for incident response

## Safety First

**CRITICAL SAFETY RULES:**
1. Never handle malware samples outside an isolated analysis environment
2. Always use password-protected archives for storage/transfer (password: "infected")
3. Never execute samples on production systems
4. Rename executable extensions during storage (.exe → .exe.sample)
5. Disable auto-execution/auto-open features in your environment
6. Document all sample handling for chain of custody

## Step-by-Step Instructions

### Step 1: Search for Sample

```bash
# Search MalwareBazaar by hash
python3 scripts/sample_downloader.py --hash <sha256_hash>

# Search by tag/family
python3 scripts/sample_downloader.py --tag emotet --limit 5

# Search by signature
python3 scripts/sample_downloader.py --signature "win.emotet"
```

### Step 2: Download and Verify

```bash
# Download with automatic verification
python3 scripts/sample_downloader.py --hash <sha256> --output ./quarantine/

# The script will:
# 1. Download to quarantine directory
# 2. Verify SHA256 hash matches
# 3. Store in password-protected ZIP
# 4. Log acquisition metadata
```

### Step 3: Register in Sample Database

```bash
# Add to local sample database
python3 scripts/sample_manager.py --add ./quarantine/sample.zip \
    --family "emotet" --source "malwarebazaar" --notes "Campaign analysis"

# Search local database
python3 scripts/sample_manager.py --search --family "emotet"

# Generate inventory report
python3 scripts/sample_manager.py --inventory
```

## Sample Sources

### Free / Open Sources
| Source | Access | API | Notes |
|--------|--------|-----|-------|
| [MalwareBazaar](https://bazaar.abuse.ch) | Free | Yes | Abuse.ch project, community uploads |
| [Malshare](https://malshare.com) | Free (API key) | Yes | Free malware repository |
| [VirusTotal](https://virustotal.com) | Free (limited) | Yes | Download requires premium API |
| [theZoo](https://github.com/ytisf/theZoo) | Free | Git | Curated live malware collection |
| [vx-underground](https://vx-underground.org) | Free | Yes | Large malware collection |
| [CAPE Sandbox](https://capesandbox.com) | Free | Yes | Public sandbox with sample download |
| [Any.Run](https://any.run) | Free tier | Yes | Interactive sandbox |
| [Hybrid Analysis](https://hybrid-analysis.com) | Free | Yes | CrowdStrike sandbox |

### API Environment Variables
```bash
export MALWAREBAZAAR_API_KEY="your-key"  # Optional for bazaar.abuse.ch
export VT_API_KEY="your-key"             # Required for VirusTotal downloads
export MALSHARE_API_KEY="your-key"       # Required for Malshare
```

## Storage Best Practices

### Directory Structure
```
samples/
├── quarantine/          # Newly downloaded, unanalyzed
├── active/              # Currently being analyzed
├── analyzed/            # Analysis complete
├── benign/              # Confirmed clean (false positives)
└── database.sqlite      # Sample metadata database
```

### Naming Convention
```
<sha256_first8>_<family>_<date>.<ext>.sample
Example: a1b2c3d4_emotet_20260321.exe.sample
```

### Chain of Custody
Document for each sample:
- Source (URL, feed, submission)
- Download timestamp
- Handler (analyst name)
- Hash verification result
- Analysis status
- Storage location

## Related Skills

- `initial-triage` — First analysis of acquired samples
- `analysis-environment-setup` — Prepare isolated environment
- `static-analysis` — Begin analysis workflow