/aminet-scanner

name: aminet-scanner
description: "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."
metadata:
  extensions:
    gsd-skill-creator:
      triggers:
        intents:
          - "scan.*aminet|aminet.*scan"
          - "virus.*check|check.*virus"
          - "quarantine"
          - "heuristic.*scan"
        files:
          - "src/aminet/signature-scanner.ts"
          - "src/aminet/heuristic-scanner.ts"
          - "src/aminet/scan-orchestrator.ts"
          - "src/aminet/quarantine.ts"
          - "src/aminet/signature-db.ts"
        contexts:
          - "aminet virus scanning"
          - "package security"
        threshold: 0.7
      token_budget: "1.5%"
      version: 1
      enabled: true
      plan_origin: "242-aminet-integration"
      phase_origin: "242"

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:**

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:**

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:**

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:**

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.