Isotope — pr0t31n

How It Works

⚠️ Authorized Testing Only

This tool interacts with live systems and must only be used for testing that has been explicitly authorized by the asset owner. Unauthorized use of this tool to probe, scan, exploit, or otherwise interact with systems you do not have written permission to test is illegal under computer fraud and abuse laws (CFAA, CMA, and international equivalents). pr0t31n does not condone or recommend any unauthorized use. Always obtain a signed Rules of Engagement (RoE) or Statement of Work (SoW) before beginning any assessment.

🛡️ Sensitive Data Handling

This tool collects, processes, or stores data that may include sensitive, personally identifiable, or client-proprietary information — even when sourced from public repositories or non-client-controlled systems. Handle all collected data in accordance with your engagement’s data handling agreement, applicable privacy regulations (GDPR, CCPA, HIPAA), and your organization’s data classification policy. Store findings in encrypted, access-controlled locations and destroy data per the agreed retention schedule.

Isotope performs comprehensive file analysis across multiple dimensions: identification, entropy measurement, string extraction, code analysis, metadata extraction, binary/executable analysis, secrets scanning, cryptographic hashing with IOC (Indicator of Compromise) lookup, and recursive archive decomposition. It accepts one or more files or directories as input and produces a structured JSON report of findings.

The analysis pipeline begins with magic-byte identification using an internal database of file signatures, then calculates Shannon entropy to detect encrypted or compressed content. For executables, Isotope examines headers (PE, ELF, Mach-O), imported libraries, and suspicious API calls. For documents and archives, it recursively decomposes nested content (ZIP, TAR, GZIP, RAR, 7z, Office documents) and analyses each embedded file individually. String extraction identifies URLs, email addresses, IP addresses, API keys, and other sensitive patterns.

Isotope integrates with the pr0t31n_threat_intel module to check file hashes against known-malicious indicator lists. When run under Crucible (CRUCIBLE_MANAGED=1), it emits structured protocol tokens for real-time progress tracking and finding delivery. All findings conform to the universal pr0t31n output schema.

Phase Pipeline

Phase 1 — little
Phase 7 — AArch64

Security

CLI tool. Processes files locally with no network access. Recursive archive extraction limits depth to prevent zip bombs.

Features

Analysis

Binary/Executable Analysis

Examines PE, ELF, and Mach-O executables for imported libraries, suspicious API calls, section anomalies, and known-bad patterns.

Code Analysis

Analyses source code and script files for dangerous functions, command injection patterns, and insecure coding practices.

Metadata Extraction

Extracts document metadata (author, creation date, software version, GPS coordinates) from Office documents, PDFs, and images.

Recursive Archive Decomposition

Recursively unpacks nested archives (ZIP, TAR, GZIP, RAR, 7z, Office OOXML) and analyses each embedded file individually.

Magic-Bytes Identification

35+ file type signatures (PNG, JPEG, PDF, ZIP, ELF, PE, Mach-O, OLE2, SQLite, Redis, PEM/DER) without libmagic dependency

Shannon Entropy Analysis

Detects encrypted or compressed content via entropy scoring with likely_encrypted/possibly_encrypted classification

Packer Detection

Detects 8 executable packers (UPX, Themida, ASPack, PECompact, Petite, NsPack, MEW, MPRESS) in PE binaries

Extraction

String Extraction

Extracts and categorises strings including URLs, email addresses, IP addresses, file paths, registry keys, and potential credentials.

Secrets Scanning

Identifies hardcoded API keys, tokens, passwords, private keys, and other sensitive material embedded in files.

Identification

Magic Byte Detection

Identifies file types using an extensive internal magic bytes database, independent of file extension.

Entropy Analysis

Calculates Shannon entropy to detect encrypted, compressed, or packed content that may indicate obfuscation or malware packing.

Integration

Cross-Tool Action Items

Auto-generates action items: URLs to Fracture, IPs to SS3, DB connection strings to Auger, cloud creds to Forge, API keys to Siphon

Intelligence

IOC Hash Lookup

Computes MD5, SHA-1, and SHA-256 hashes and checks them against threat intelligence indicator lists for known-malicious files.

Output

Universal Schema Output

Produces findings in the pr0t31n universal schema with structured evidence files and run-directory-relative paths.

Use Cases

Malware Indicator Assessment

Analyse suspicious files collected during an engagement for malware indicators: packed executables, encrypted payloads, known-bad hashes, and suspicious API imports.

Sensitive Data Discovery

Scan firmware images, configuration archives, or document collections for hardcoded credentials, API keys, private keys, and other secrets.

Firmware Analysis

Decompose firmware update packages (often nested archives) and analyse embedded binaries, scripts, and configuration files for security issues.

Document Metadata Forensics

Extract metadata from documents to identify authors, software versions, internal paths, and GPS coordinates that may reveal sensitive organisational information.

Pre-Engagement File Vetting

Vet files provided by a client (configuration exports, application packages) before importing them into the testing environment.

CLI Reference

Command Examples

Analyze File

python3 isotope.py --file /path/to/suspicious_file --output-dir /path/to/output

Run all 9 analysis modules on a file.

Analyze Directory

python3 isotope.py --dir /path/to/firmware/ --output-dir /path/to/output

Analyze all files in a directory.

Finding Nomenclature

Isotope findings use descriptive titles rather than ID prefixes. Findings are categorised by analysis module: identification, entropy, strings, code, metadata, binary, secrets, hashing, archive, certificate. Each module can produce multiple finding types (e.g., secrets module produces per-pattern-family findings for AWS keys, tokens, connection strings, etc.).

Action Items

Isotope generates action items for suspicious findings — e.g., "Investigate hardcoded API key found in binary strings", "Submit hash to VirusTotal for malware analysis", "Examine high-entropy section for packed/encrypted payload".

Output Files

File	Format	Description
`meta.json`	JSON	Tool identity and engagement metadata
`findings.json`	JSON	Universal findings array v1.1
`findings.csv`	CSV	CSV mirror of findings
`summary.json`	JSON	Aggregated statistics
`scan.log`	TXT	Human-readable timestamped log
`scan.log.json`	JSONL	Machine-readable JSON log events
`errors.log`	TXT	ERROR-level entries only

Invocation Methods

Method	Usage
CLI — Direct	`cd /opt/pr0t31n/Isotope && python3 isotope.py [OPTIONS]` Run directly with command-line arguments.
Crucible-Managed	Launched and managed by Crucible (port 5100). Crucible handles start/stop/pause, log streaming, findings aggregation, and status tracking.

Integration

Used By

Crucible (manages)

Third-Party Dependencies & Credits

Tool / Library	Developer	Type	Link
python-magic	Adam Hupp	python	https://github.com/ahupp/python-magic
Pillow	Jeffrey A. Clark (Alex) / Pillow Team	python	https://github.com/python-pillow/Pillow
PyPDF2 / pypdf	Mathieu Fenniak / py-pdf contributors	python	https://github.com/py-pdf/pypdf
olefile	Philippe Lagadec	python	https://github.com/decalage2/olefile
ssdeep (Python)	Helmut Grohne / DinoTools	python	https://github.com/DinoTools/python-ssdeep
TLSH	Trend Micro	python	https://github.com/trendmicro/tlsh
cryptography	Python Cryptographic Authority	python	https://github.com/pyca/cryptography

Metadata

Name	Isotope
Category	Analysis
Version	1.3.4
Install Path	`/opt/pr0t31n/Isotope`
Main File	`isotope.py`
GitHub	https://github.com/pr0t31n/Isotope.git