skills/docs/security-stack/security/security-codes/src/patterns/entropy.md

entropy

Purpose

Detects high-entropy strings that are likely secret tokens, API keys, or passwords using Shannon entropy analysis. This heuristic catches secrets that have no fixed prefix and would be missed by pattern-based detectors. While less precise than dedicated pattern detectors, it provides a useful catch-all for novel or unrecognized credential formats.

Features

• Scans for base64/hex-alphabet runs of at least 20 characters.
• Computes Shannon entropy (bits per character) for each candidate.
• Returns only candidates with entropy ≥ 4.5 bits per character, a threshold calibrated to separate random tokens from natural-language substrings.
• Returns a deliberately conservative confidence of 0.6 to reflect the heuristic nature of the detection.

Usage: Basic Example

import { detect } from '@suaveplan/security-codes/patterns/entropy';

// A random-looking base64 string
const matches = detect('secret=aB3dEfGhIjKlMnOpQrStUvWxYz012345678901');
// matches[0].type === 'high-entropy', confidence 0.6

Usage: Advanced Example

import { detect } from '@suaveplan/security-codes/patterns/entropy';

// Short or low-entropy strings are not flagged
const noMatch = detect('hello world this is plain text');
console.log(noMatch.length); // 0

// High-entropy token is flagged
const match = detect('TOKEN=xK8mP2nQ9rS5tV7wY1aB4cD6eF0gH3iJ');
console.log(match[0].confidence); // 0.6

API Reference

detect(input: string): SecurityCodeMatch[]

Scans input for high-entropy strings.

Parameter	Type	Description
input	string	The string to scan

Returns an array of SecurityCodeMatch with type: 'high-entropy' and confidence: 0.6. Returns an empty array when no high-entropy candidates are found.

Implementation Notes

Shannon entropy H = -∑ p(x) log₂ p(x) over a string's character frequency distribution. Natural English text scores around 3.5–4.0 bits per character; random tokens typically exceed 4.5. The threshold was chosen empirically to minimise false positives on common identifiers and UUIDs while still catching hex-encoded secrets and base64 tokens. The minimum length of 20 characters filters out short words that happen to have high entropy due to their brevity.