Skip to content

meltedinhex/analyst-ai-pack / skills/triaging-an-unknown-sample

triaging-an-unknown-sample

Verified

Performs fast first-pass triage of an unknown file to decide depth of analysis: file type identification, hashing, reputation lookup, packing/entropy check, and string review. Activates for requests to triage, classify, or do initial assessment of an unknown or suspicious file.

FileKindSize
LICENSEother340 B
SKILL.mdskill md3.9 KB
references/api-reference.mdmarkdown1.6 KB
scripts/analyst.pyscript3.8 KB

references/api-reference.md

View on GitHub
# API Reference: Triaging an Unknown Sample

## Overview

`scripts/analyst.py` performs static first-pass triage: magic-byte type identification,
hashing, Shannon entropy (packing signal), categorized strings, and a simple suspicion
score with an escalation recommendation. An optional VirusTotal hash lookup adds reputation.

## Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| (stdlib) | — | Hashing, entropy, regex, optional `urllib` for VT |

## External tools

| Tool | Purpose |
|------|---------|
| file / libmagic | Authoritative type identification beyond the built-in magic set |
| VirusTotal API | Hash reputation (lookup only; no upload) |

## Core functions

### `triage(filepath)`
Returns type, size, sha256, entropy, `likely_packed`, `embedded_pe`, suspicious strings,
a `triage_score`, and a `recommendation` (`low-signal` / `review` / `deep-analysis`).

### `shannon_entropy(data)`
Byte-level Shannon entropy in bits (0–8). Values above ~7.2 suggest packing/encryption.

### `identify(data)`
Magic-byte file-type label.

### `reputation(sha256, vt_key)`
Looks up a hash on VirusTotal v3 and returns `last_analysis_stats`. Never uploads the file.

## Usage

```bash
python scripts/analyst.py triage sample.bin
python scripts/analyst.py reputation --sha256 <sha256> --vt-key "$VT_API_KEY"
```

## Sources

- file(1) / libmagic manual — https://man7.org/linux/man-pages/man1/file.1.html
- VirusTotal API v3 reference — https://docs.virustotal.com/reference/overview
- Shannon entropy as a packing indicator (information theory; standard practice)
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall