⚠️ LEGAL NOTICE — Authorised security testing ONLY.
Using this tool against systems you do not own or have explicit written permission to test is illegal under the Computer Fraud and Abuse Act (US), Computer Misuse Act (UK), and equivalent laws worldwide. See SECURITY.md.
Table of Contents
What is CredAttack?
CredAttack is a modular, production-grade credential testing suite for authorised penetration testing engagements. It covers the full credential-attack lifecycle:
| Phase | CredAttack Capability |
|---|
| Reconnaissance | Default creds DB (200+ pairs), smart username-derived pattern generation |
Attack Modes
Supported Protocols
Architecture
credattack.py ← CLI (Typer) — 8 attack-mode subcommands
│
├── credattack/core/
│ ├── config.py ← Pydantic v2 Settings, CREDATTACK_* env-var overrides
│ ├── engine.py ← AttackEngine (ThreadPoolExecutor + Rich progress UI)
│ ├── lockout.py ← LockoutDetector (sliding-window, thread-safe)
│ ├── proxy.py ← ProxyRotator (round-robin, health-check, demotion)
│ ├── mutator.py ← PasswordMutator (leet, seasonal, suffix, keyboard-walk…)
│ ├── result.py ← AttemptResult + SessionReport dataclasses
│ ├── report.py ← Jinja2 HTML report generator
│ └── logger.py ← Rich logging + JSONL audit writer
│
├── credattack/protocols/
│ └── *.py ← 18 ProtocolAttacker implementations
│
├── credattack/data/
│ ├── default_creds.json ← 200+ real default credential pairs
│ ├── smart_patterns.json ← 140+ enterprise password templates
│ └── wordlists/ ← Per-service default password lists
│
└── tests/ ← 50+ pytest tests (unit + protocol mocks)
Quick Start
# Clone and set up
git clone https://github.com/amibhai/credential-attacks-toolkit.git
cd credential-attacks-toolkit
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
# Check version
python credattack.py --version
# Dry-run (no connections made — verify your word lists)
python credattack.py ssh -t 192.168.1.100 -u admin -P wordlists/common_passwords.txt --dry-run
# Real SSH dictionary attack
python credattack.py ssh -t 192.168.1.100 -u admin -P /path/to/rockyou.txt
# Password spray (rate-limited, lockout-safe)
python credattack.py spray -t 192.168.1.100 --protocol ssh -U users.txt -p "Summer2024!" --delay 30
# Smart mode — generate patterns from username + company
python credattack.py smart -t 192.168.1.100 --protocol ssh -u john.doe --company ACME
# Try service defaults
python credattack.py defaults -t 192.168.1.100 --protocol mysql
# Multi-target campaign
python credattack.py multi --targets hosts.txt --protocol ssh -U users.txt -P passes.txt
Installation
Option A — pip + virtualenv (recommended)
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt
Option B — Makefile shortcuts
make install # core deps
make install-dev # + pytest-cov, ruff, mypy
Option C — Docker
docker build -t credattack -f docker/Dockerfile .
docker run --rm credattack --help
# Mount your wordlists and collect output
docker run --rm \
-v $(pwd)/wordlists:/app/wordlists:ro \
-v $(pwd)/output:/app/output \
credattack ssh -t 192.168.1.100 -u admin -P wordlists/common_passwords.txt
CLI Reference
Global options
python credattack.py [OPTIONS] COMMAND [ARGS]...
Options:
-V, --version Show version and exit.
--help Show help.
Common flags (available on all protocol commands)
Subcommands
# Protocol-specific (each maps to a dedicated attacker)
python credattack.py ssh|ftp|smb|rdp|smtp|pop3|imap|mysql|mssql|redis|mongodb|winrm|ldap|telnet|vnc \
-t HOST -u USER -P passes.txt
# HTTP (form / basic / digest)
python credattack.py http -t http://target/login --mode form \
--form-user-field username --form-pass-field password --success-string "Dashboard"
# Spray — single password, many users, long delay
python credattack.py spray -t HOST --protocol ssh -U users.txt -p "Password1" --delay 30
# Combo — cartesian product users × passwords
python credattack.py combo -t HOST --protocol smb -U users.txt -P passes.txt
# Smart — OSINT-derived generation
python credattack.py smart -t HOST --protocol ssh -u firstname.lastname --company TargetCorp
# Defaults — try vendor default credentials
python credattack.py defaults -t HOST --protocol mysql
# Multi — same attack across multiple hosts
python credattack.py multi --targets hosts.txt --protocol ssh -U users.txt -P passes.txt
# Full — all protocols in sequence
python credattack.py full -t HOST -U users.txt -P passes.txt
Password Mutation Engine
PasswordMutator in credattack/core/mutator.py supports composable strategies:
from credattack.core.mutator import PasswordMutator
m = PasswordMutator(max_mutations=5000)
# All strategies combined
for pw in m.smart_generate("john.doe", company="ACME"):
print(pw)
# Just seasonal patterns
for pw in m.seasonal_patterns(company="Contoso"):
print(pw)
Default Credentials Database
credattack/data/default_creds.json contains 200+ real default credential pairs across:
Cisco · F5 · Juniper · Palo Alto · VMware · Jenkins · GitLab · Tomcat · WordPress · MySQL · MSSQL · Redis · MongoDB · PostgreSQL · Elasticsearch · RabbitMQ · Splunk · Nagios · Zabbix · pfSense · MikroTik · Huawei · HP iLO · Dell iDRAC · IPMI
# See all defaults for a service
python credattack.py defaults -t HOST --protocol mysql --dry-run
# Run against target
python credattack.py defaults -t 10.0.0.1 --protocol ssh
Proxy Rotation
Pass a proxy file (one proxy per line, host:port format):
# proxies.txt
192.168.1.10:1080
192.168.1.11:1080
socks5://10.0.0.5:9050
python credattack.py ssh -t TARGET -u admin -P passes.txt --proxy-file proxies.txt
The ProxyRotator performs health-checks on startup and demotes proxies that exceed a failure-rate threshold. Dead proxies are automatically excluded.
HTML Reports
After every non-dry-run attack an HTML report is auto-generated in ./output/:
- Stat cards: total attempts, success rate, duration, attempts/sec
- Found credentials table: host · protocol · username · password (copy-to-clipboard)
- Dark-theme Jinja2 template
# Open after a run
start output/report_*.html # Windows
open output/report_*.html # macOS
Configuration & Environment Variables
All settings in credattack/core/config.py can be overridden via CREDATTACK_* environment variables:
export CREDATTACK_THREADS=20
export CREDATTACK_TIMEOUT=3.0
export CREDATTACK_DELAY=1.0
export CREDATTACK_JITTER=0.5
export CREDATTACK_LOCKOUT_THRESHOLD=3
export CREDATTACK_VERBOSITY=2
Or at the CLI level with the standard flags (--threads, --timeout, etc.).
Docker
# Build image
docker build -t credattack -f docker/Dockerfile .
# Run with Docker Compose
cd docker
docker compose run credattack ssh -t 192.168.1.100 -u admin -P /app/wordlists/common_passwords.txt
# Set config via environment
docker run --rm \
-e CREDATTACK_THREADS=20 \
-e CREDATTACK_TIMEOUT=3 \
-v $(pwd)/output:/app/output \
credattack defaults -t 10.0.0.1 --protocol mysql
Testing
# Run all tests
pytest -q
# With coverage
pytest --cov=credattack --cov-report=term-missing -q
# Makefile shortcut
make test-cov
Current suite: 50+ tests covering:
Wordlists
⚠️ The bundled wordlists/ files are minimal smoke-test stubs. Supply your own for real assessments.
Recommended sources
# Use any external wordlist
python credattack.py ssh -t TARGET -u admin -P /opt/wordlists/rockyou.txt
Project Structure
credential-attacks-toolkit/
├── credattack.py # CLI entrypoint (Typer)
├── pyproject.toml # PEP 517/518 build & tool config
├── requirements.txt # Runtime deps
├── Makefile # Developer shortcuts
├── VERSION # Single source of version truth
├── CHANGELOG.md
├── SECURITY.md
├── .github/
│ └── workflows/ci.yml # GitHub Actions: lint + test matrix + mypy
├── docker/
│ ├── Dockerfile
│ └── docker-compose.yml
├── credattack/
│ ├── core/
│ │ ├── config.py # Pydantic v2 Settings
│ │ ├── engine.py # AttackEngine (ThreadPoolExecutor)
│ │ ├── lockout.py # LockoutDetector (sliding window)
│ │ ├── proxy.py # ProxyRotator
│ │ ├── mutator.py # PasswordMutator
│ │ ├── result.py # AttemptResult, SessionReport
│ │ ├── report.py # HTML report generator
│ │ └── logger.py # Rich logger + JSONL writer
│ ├── protocols/ # 18 ProtocolAttacker implementations
│ │ └── base.py # Abstract ProtocolAttacker
│ └── data/
│ ├── default_creds.json # 200+ vendor defaults
│ ├── smart_patterns.json # 140+ enterprise templates
│ └── wordlists/ # Per-service starter lists
├── tests/
│ ├── conftest.py # Shared fixtures
│ ├── test_lockout.py
│ ├── test_mutator.py
│ ├── test_mutator_extended.py
│ ├── test_proxy.py
│ ├── test_result.py
│ ├── test_protocols_ssh.py
│ ├── test_protocols_ftp.py
│ └── test_protocols_http.py
├── wordlists/ # Minimal smoke-test stubs
└── output/ # Generated logs & reports (git-ignored)
Attack Success Rates (Indicative)
Contributing
See CONTRIBUTING.md.
Please open an issue before submitting large PRs.
All contributions must adhere to the ethical use policy in SECURITY.md.
Use responsibly. Test ethically. Stay legal.
amibhai/credential-attacks-toolkit
