258 lines
10 KiB
Markdown
258 lines
10 KiB
Markdown
# Credential Enumeration Tool — Design Spec
|
|
|
|
## Overview
|
|
|
|
A post-access credential enumeration tool written in Nim that scans Linux systems for exposed secrets across 7 categories. Compiles to a single static binary with zero dependencies — drop on target, run, get a structured report of every credential file, its exposure level, and severity rating.
|
|
|
|
**Language:** Nim 2.2.x
|
|
**Binary name:** `credenum`
|
|
**Architecture:** Modular collector pattern — one module per credential category, common interface, central runner
|
|
|
|
---
|
|
|
|
## Core Types (`src/types.nim`)
|
|
|
|
- **Severity** — enum: `info`, `low`, `medium`, `high`, `critical`
|
|
- **Category** — enum: `browser`, `ssh`, `cloud`, `history`, `keyring`, `git`, `apptoken`
|
|
- **Credential** — discovered credential data (source, credential type, value or redacted preview, metadata)
|
|
- **Finding** — a single discovery (path, category, severity, description, optional Credential, file permissions, timestamps)
|
|
- **CollectorResult** — `seq[Finding]` + collector metadata (name, duration, errors encountered)
|
|
- **HarvestConfig** — runtime configuration (target home dir, enabled modules, exclude patterns, output format, flags)
|
|
- **Report** — all collector results + summary stats + timestamp + target info
|
|
|
|
**Severity assignment rules:**
|
|
- Critical: plaintext credentials in world-readable files
|
|
- High: unprotected private keys, plaintext credential stores
|
|
- Medium: overly permissive file permissions on credential files
|
|
- Low: credential files exist but properly permissioned
|
|
- Info: enumeration data (host lists, profile counts, existence checks)
|
|
|
|
---
|
|
|
|
## Collector Modules
|
|
|
|
Each module exports `proc collect(config: HarvestConfig): CollectorResult`. The runner calls each in sequence. No inheritance needed — just a common return type and a seq of collector procs populated at init.
|
|
|
|
### 1. Browser Credential Store Scanner (`src/collectors/browser.nim`)
|
|
- Firefox: locate profiles via `profiles.ini`, check `logins.json`, `cookies.sqlite`, `key4.db`
|
|
- Chromium: locate `Login Data`, `Cookies`, `Web Data` SQLite databases
|
|
- Report: file locations, permissions, entry counts, last-modified timestamps
|
|
- Flag world-readable/group-readable databases as critical
|
|
- Detection + metadata level (no decryption)
|
|
|
|
### 2. SSH Key & Config Auditor (`src/collectors/ssh.nim`)
|
|
- Scan `~/.ssh/` for private keys (RSA, Ed25519, ECDSA, non-standard filenames)
|
|
- Read key headers to determine passphrase protection (encrypted PEM vs unencrypted)
|
|
- Flag unprotected keys as high severity
|
|
- Check permissions (keys=600, directory=700)
|
|
- Parse `~/.ssh/config` — enumerate hosts, identify weak settings
|
|
- Read `authorized_keys` and `known_hosts` for enumeration
|
|
|
|
### 3. Cloud Provider Config Scanner (`src/collectors/cloud.nim`)
|
|
- AWS: `~/.aws/credentials`, `~/.aws/config` — count profiles, identify static vs session keys
|
|
- GCP: `~/.config/gcloud/` — application default credentials, service account keys
|
|
- Azure: `~/.azure/` — access tokens, profile info
|
|
- Kubernetes: `~/.kube/config` — enumerate contexts, clusters, auth methods
|
|
- Permission checks, flag anything broader than owner-only
|
|
|
|
### 4. Shell History & Environment Scanner (`src/collectors/history.nim`)
|
|
- Read `.bash_history`, `.zsh_history`, `.fish_history`
|
|
- Pattern match for inline secrets: KEY=, SECRET=, TOKEN=, PASSWORD= exports, DB connection strings, curl/wget with auth headers
|
|
- Scan for `.env` files in home directory tree
|
|
- Report: file, line region, redacted preview
|
|
|
|
### 5. Keyring & Password Store Scanner (`src/collectors/keyring.nim`)
|
|
- GNOME Keyring: `~/.local/share/keyrings/`
|
|
- KDE Wallet: `~/.local/share/kwalletd/`
|
|
- KeePass/KeePassXC: search for `.kdbx` files
|
|
- pass (password-store): `~/.password-store/`
|
|
- Bitwarden: `~/.config/Bitwarden/` local vault data
|
|
- Report locations, file sizes, permissions, last modified
|
|
|
|
### 6. Git Credential Store Scanner (`src/collectors/git.nim`)
|
|
- `~/.git-credentials` — plaintext storage (high severity)
|
|
- `~/.gitconfig` — check `credential.helper` setting
|
|
- Search for credential cache socket files
|
|
- Check for GitHub/GitLab PATs in config files
|
|
|
|
### 7. Application Token Scanner (`src/collectors/apptoken.nim`)
|
|
- Slack: `~/.config/Slack/` session/cookie storage
|
|
- Discord: `~/.config/discord/` token storage
|
|
- VS Code: `~/.config/Code/` stored secrets
|
|
- Database configs: `~/.pgpass`, `~/.my.cnf`, Redis configs
|
|
- MQTT broker configs, common application credential files
|
|
|
|
---
|
|
|
|
## CLI Interface
|
|
|
|
```
|
|
credenum [flags]
|
|
|
|
Flags:
|
|
--target <user> Target user home directory (default: current user)
|
|
--modules <list> Comma-separated module list (default: all)
|
|
--exclude <patterns> Glob patterns for paths to skip
|
|
--format <fmt> Output format: terminal, json, both (default: terminal)
|
|
--output <path> Write JSON output to file
|
|
--dry-run List paths that would be scanned without reading
|
|
--quiet Suppress banner and progress, output findings only
|
|
--verbose Show all scanned paths, not just findings
|
|
```
|
|
|
|
**CLI parsing:** `std/parseopt` (stdlib, no dependencies)
|
|
|
|
---
|
|
|
|
## Terminal Output Design
|
|
|
|
Hacker-aesthetic terminal output:
|
|
- ASCII art banner with tool name and version
|
|
- Box-drawing characters for section borders
|
|
- Color-coded severity badges (critical=red, high=magenta, medium=yellow, low=cyan, info=dim)
|
|
- Clean table formatting for findings
|
|
- Summary footer with totals by severity, modules scanned, duration
|
|
- Progress indicators showing which module is currently scanning
|
|
|
|
---
|
|
|
|
## Output Formats
|
|
|
|
### Terminal (ANSI)
|
|
Colored, formatted output designed for interactive use. Banner, per-module sections, severity badges, summary.
|
|
|
|
### JSON
|
|
Structured report:
|
|
```json
|
|
{
|
|
"metadata": { "timestamp": "...", "target": "...", "version": "...", "duration_ms": 0 },
|
|
"modules": [
|
|
{
|
|
"name": "ssh",
|
|
"findings": [
|
|
{
|
|
"category": "ssh",
|
|
"severity": "high",
|
|
"path": "/home/user/.ssh/id_rsa",
|
|
"description": "Unprotected private key (no passphrase)",
|
|
"permissions": "0644",
|
|
"modified": "2026-01-15T10:30:00Z"
|
|
}
|
|
],
|
|
"duration_ms": 12,
|
|
"errors": []
|
|
}
|
|
],
|
|
"summary": { "critical": 2, "high": 5, "medium": 8, "low": 3, "info": 12 }
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Build & Distribution
|
|
|
|
### Static binary via musl
|
|
- `config.nims` configures musl-gcc for fully static Linux binaries
|
|
- Zero runtime dependencies
|
|
|
|
### Cross-compilation
|
|
- x86_64-linux (primary)
|
|
- aarch64-linux (ARM64)
|
|
- Uses zig cc for cross-compilation
|
|
- Justfile tasks: `just build-x86`, `just build-arm64`
|
|
|
|
### Build modes
|
|
- `just build` — debug build with all checks
|
|
- `just release` — optimized static binary (`-d:release -d:lto --opt:size`)
|
|
- `just release-small` — stripped + UPX compressed
|
|
|
|
### Justfile tasks
|
|
- `just build` / `just release` / `just release-small`
|
|
- `just test` — run unit tests
|
|
- `just docker-test` — build + run in Docker test environment
|
|
- `just fmt` — format with nph
|
|
- `just clean`
|
|
|
|
---
|
|
|
|
## Docker Test Environment
|
|
|
|
**`tests/docker/Dockerfile`** — Ubuntu-based container planting fake credentials across all 7 categories:
|
|
|
|
- SSH: test key pairs (some protected, some not), various permissions
|
|
- Browser: mock Firefox profile with dummy `logins.json`, mock Chromium dirs
|
|
- Cloud: fake AWS credentials, dummy GCP service account JSON, mock kubeconfig
|
|
- History: seeded `.bash_history`/`.zsh_history` with fake tokens
|
|
- Keyrings: mock `.kdbx`, mock `pass` store
|
|
- Git: `.git-credentials` with dummy entries
|
|
- App tokens: mock Slack/Discord/VS Code configs, `.pgpass`, `.my.cnf`
|
|
|
|
All values are obviously fake (`AKIA_FAKE_ACCESS_KEY_12345`).
|
|
|
|
`just docker-test` builds, runs credenum inside, validates all findings discovered with correct severity.
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
credential-enumeration/
|
|
├── src/
|
|
│ ├── harvester.nim # Entry point, CLI parsing
|
|
│ ├── config.nim # Constants, paths, patterns, severities
|
|
│ ├── types.nim # Core types
|
|
│ ├── runner.nim # Execute collectors, aggregate results
|
|
│ ├── output/
|
|
│ │ ├── terminal.nim # ANSI terminal output with hacker aesthetic
|
|
│ │ └── json.nim # JSON serialization
|
|
│ └── collectors/
|
|
│ ├── base.nim # Collector registration
|
|
│ ├── browser.nim
|
|
│ ├── ssh.nim
|
|
│ ├── cloud.nim
|
|
│ ├── history.nim
|
|
│ ├── keyring.nim
|
|
│ ├── git.nim
|
|
│ └── apptoken.nim
|
|
├── tests/
|
|
│ └── docker/
|
|
│ ├── Dockerfile
|
|
│ └── planted/ # Mock credential files
|
|
├── learn/
|
|
│ ├── 00-OVERVIEW.md
|
|
│ ├── 01-CONCEPTS.md
|
|
│ ├── 02-ARCHITECTURE.md
|
|
│ ├── 03-IMPLEMENTATION.md
|
|
│ └── 04-CHALLENGES.md
|
|
├── config.nims # Build config (static linking, cross-compile)
|
|
├── credential-enumeration.nimble # Package manifest
|
|
├── Justfile
|
|
├── install.sh
|
|
├── README.md
|
|
├── LICENSE
|
|
└── .gitignore
|
|
```
|
|
|
|
---
|
|
|
|
## Learn Folder
|
|
|
|
- **00-OVERVIEW.md** — What credential enumeration is, why it matters, prerequisites, quick start
|
|
- **01-CONCEPTS.md** — Linux credential storage locations, file permission model, where apps store secrets and why defaults are insecure. Real-world breach references.
|
|
- **02-ARCHITECTURE.md** — Modular collector design, data flow, why Nim for security tooling
|
|
- **03-IMPLEMENTATION.md** — Code walkthrough: core types, collector pattern, CLI parsing, output formatting, Nim type system and modules
|
|
- **04-CHALLENGES.md** — Extensions: new collectors, encrypted output, network enumeration, framework integration
|
|
|
|
---
|
|
|
|
## What This Project Teaches
|
|
|
|
- Linux credential storage locations across browsers, SSH, cloud tools, shells, keyrings, Git, and applications
|
|
- File permission models and their security implications
|
|
- Nim programming: static compilation, module system, type system, FFI potential
|
|
- Why Nim is adopted in the security assessment community (small static binaries, C-level performance)
|
|
- Modular tool architecture with common interfaces
|
|
- Building visually polished CLI tools
|
|
- Docker-based testing for security tools
|
|
- Cross-compilation and static linking for portable binaries
|