# Aminet Scanner

> Multi-layer virus scanning for Aminet packages. Signature-based detection, heuristic hunk analysis, boot block scanning, quarantine management, and scan orchestration. Use when scanning packages, checking virus status, or managing quarantine.

- Skill: `majiayu000/aminet-scanner` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/aminet-scanner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/aminet-scanner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/aminet-scanner

---


# Aminet Scanner

## Purpose

Provides multi-layer virus scanning for Aminet packages targeting the Amiga malware landscape. Combines signature-based detection (52 virus signatures in ClamAV .ndb format), heuristic analysis of hunk structures and boot blocks, quarantine management with atomic file isolation, and a scan orchestrator that coordinates all layers into unified scan reports with configurable depth levels.

## Capabilities

- 52 virus signatures across 3 JSON database files (boot block, file, hunk viruses)
- Context-aware scanBuffer with hex pattern matching and wildcard bitmasks
- Boot block and hunk type dispatch for targeted scanning
- Sub-2-second scanning for 500KB files against 50 signatures
- Last-wins deduplication for extensible signature JSON drop-in
- 8 heuristic rules: 4 hunk-based, 4 boot block-based
- Zero false positives on legitimate Amiga files
- Worst-case verdict derivation across all findings
- Quarantine with atomic file moves and metadata sidecars
- Path traversal prevention on quarantine operations
- Restore round-trip (quarantine and recover)
- FS-UAE + CheckX emulated scanning with AbortController timeout
- Community checksum cross-reference for known-good verification
- Scan orchestrator coordinating signature + heuristic into unified ScanReport
- Configurable depth: fast (signatures only), standard (sig + heuristic), thorough (sig + heuristic + emulated)
- Batch processing with auto-quarantine for infected packages
- YAML-based scan policy with Zod validation

## Key Modules

| Module | Purpose |
|--------|---------|
| `src/aminet/signature-db.ts` | 52 virus signatures in 3 JSON files with last-wins deduplication |
| `src/aminet/signature-scanner.ts` | Context-aware hex pattern matching with wildcard bitmasks |
| `src/aminet/heuristic-scanner.ts` | 8 heuristic rules for hunk and boot block analysis |
| `src/aminet/quarantine.ts` | Atomic file isolation with metadata sidecars and restore |
| `src/aminet/scan-orchestrator.ts` | Coordinates all scan layers into unified ScanReport |
| `src/aminet/emulated-scanner.ts` | FS-UAE + CheckX emulated scanning with timeout control |

## Usage Examples

**Quick signature scan:**
```typescript
import { scanBuffer } from './signature-scanner.js';

const result = scanBuffer(fileBuffer, { context: 'hunk' });
// result.verdict: 'clean' | 'suspicious' | 'infected'
// result.findings: matched signature details
```

**Full orchestrated scan:**
```typescript
import { scanPackage } from './scan-orchestrator.js';

const report = await scanPackage(filePath, {
  depth: 'thorough', // fast | standard | thorough
  autoQuarantine: true,
  quarantineDir: './quarantine',
});
// report.verdict, report.signatureFindings, report.heuristicFindings
```

**Quarantine management:**
```typescript
import { quarantineFile, restoreFile } from './quarantine.js';

await quarantineFile(infectedPath, { quarantineDir: './quarantine', reason: 'SCA virus' });
await restoreFile(quarantinedId, { quarantineDir: './quarantine', restoreDir: './restored' });
```

**Batch scan with auto-quarantine:**
```typescript
import { batchScan } from './scan-orchestrator.js';

const results = await batchScan(filePaths, {
  depth: 'standard',
  autoQuarantine: true,
  quarantineDir: './quarantine',
});
```

## Dependencies

- Aminet hunk parser (`src/aminet/hunk-parser.ts`) for binary analysis
- Aminet boot block parser (`src/aminet/bootblock-parser.ts`) for boot sector analysis
- Node.js `node:fs` for file I/O and quarantine operations
- FS-UAE emulator (optional, for thorough/emulated scanning)
- Zod for scan policy YAML validation

## Token Budget Rationale

1.5% budget reflects the 6 modules covering the complete multi-layer scanning pipeline. The signature database format, hex pattern matching with wildcards, heuristic rule engine, quarantine atomicity, and orchestrator coordination logic require comprehensive context for correct security operation and troubleshooting.