amibhai/credential-attacks-toolkitComplete credential attack suite for authorized security testing — SSH, FTP, Web Login, Bruteforce, Dictionary attacks
# CredAttack — Credential Attacks Toolkit
<p align="center">
<img src="https://img.shields.io/badge/release-v1.3.0-brightgreen?style=for-the-badge" alt="Release">
<img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue?style=for-the-badge&logo=python" alt="Python">
<img src="https://img.shields.io/badge/protocols-17-orange?style=for-the-badge" alt="Protocols">
<img src="https://img.shields.io/badge/tests-passing-success?style=for-the-badge&logo=pytest" alt="Tests">
<img src="https://img.shields.io/badge/license-SEE--LICENSE-lightgrey?style=for-the-badge" alt="License">
</p>
> **⚠️ 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](https://github.com/amibhai/credential-attacks-toolkit/blob/main/SECURITY.md).
---
## Table of Contents
- [What is CredAttack?](#what-is-credattack)
- [Attack Modes](#attack-modes)
- [Supported Protocols](#supported-protocols)
- [Architecture](#architecture)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [CLI Reference](#cli-reference)
- [Password Mutation Engine](#password-mutation-engine)
- [Default Credentials Database](#default-credentials-database)
- [Proxy Rotation](#proxy-rotation)
- [HTML Reports](#html-reports)
- [Configuration & Environment Variables](#configuration--environment-variables)
- [Docker](#docker)
- [Testing](#testing)
- [Project Structure](#project-structure)
- [Contributing](#contributing)
---
## 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** | 17 protocol attackers, 6 attack modes, multi-target campaigns |
| **Evasion** | Lockout detection, configurable rate limiting, jitter, proxy rotation |
| **Reporting** | JSONL audit log, Jinja2 HTML report, found-creds banner + file dump |
---
## Attack Modes
| Mode | Command | Description |
|------|---------|-------------|
| **Dictionary** | `ssh`, `ftp`, `smb`, … | Wordlist against one user |
| **Spray** | `spray` | One password across a user list (lockout-safe) |
| **Combo** | `combo` | Every user × every password |
| **Smart** | `smart` | Username/company-derived pattern generation |
| **Defaults** | `defaults` | Try 200+ known service defaults |
| **Multi-target** | `multi` | Same attack across a list of hosts |
| **Full pipeline** | `full` | All protocols, one report |
---
## Supported Protocols
| # | Protocol | Module | Default Port | Notes |
|---|----------|--------|-------------|-------|
| 1 | SSH | `ssh.py` | 22 | paramiko, key/password auth |
| 2 | FTP | `ftp.py` | 21 | Active & passive mode |
| 3 | HTTP Form | `http_form.py` | 80/443 | Auto CSRF token detection |
| 4 | HTTP Basic | `http_basic.py` | 80 | RFC 7617 |
| 5 | HTTP Digest | `http_digest.py` | 80 | RFC 7616 |
| 6 | SMB | `smb.py` | 445 | impacket, NTLM |
| 7 | RDP | `rdp.py` | 3389 | impacket NLA |
| 8 | SMTP | `smtp.py` | 587 | STARTTLS |
| 9 | POP3 | `pop3.py` | 110 | APOP support |
| 10 | IMAP | `imap.py` | 143 | STARTTLS |
| 11 | MySQL | `mysql.py` | 3306 | mysql-connector-python |
| 12 | MSSQL | `mssql.py` | 1433 | pymssql |
| 13 | Redis | `redis_proto.py` | 6379 | AUTH command |
| 14 | MongoDB | `mongodb.py` | 27017 | pymongo |
| 15 | WinRM | `winrm.py` | 5985 | NTLM, pywinrm |
| 16 | LDAP | `ldap_proto.py` | 389 | ldap3, rootDSE auto-detect |
| 17 | Telnet | `telnet.py` | 23 | raw TCP |
| 18 | VNC | `vnc.py` | 5900 | Raw DES challenge-response |
---
## Architecture
```
credattack.py ← thin shim: `python credattack.py ...` from a checkout
│
├── credattack/cli.py ← CLI (Typer) — 8 attack-mode subcommands; also the
│ `credattack` console script when pip-installed
├── 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
```bash
# 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)
```bash
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
```bash
make install # core deps
make install-dev # + pytest-cov, ruff, mypy
```
### Option C — pip install (editable or from a wheel)
```bash
pip install -e . # core deps only
pip install -e .[full] # + SMB/RDP/MySQL/MSSQL/Redis/MongoDB/WinRM/LDAP
pip install -e .[dev] # + pytest/ruff/mypy
credattack --version # console script, equivalent to `python credattack.py`
```
### Option D — Docker
```bash
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)
| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--target` | `-t` | — | Target host / IP |
| `--port` | | 0 (proto default) | Override TCP port |
| `--username` | `-u` | — | Single username |
| `--user-file` | `-U` | — | Newline-separated username file |
| `--pass-file` | `-P` | — | Newline-separated password file |
| `--password` | `-p2` | — | Single password |
| `--threads` | `-n` | 10 | Concurrent workers |
| `--timeout` | `-T` | 5.0 | Per-attempt timeout (s) |
| `--delay` | `-d` | 0.0 | Fixed inter-attempt delay (s) |
| `--jitter` | | 0.0 | Max random jitter (s) |
| `--stop-on-first` | | True | Stop per-user after first hit |
| `--proxy-file` | | None | HTTP/SOCKS5 proxy list |
| `--output-dir` | `-o` | `./output` | Result directory |
| `--verbosity` | `-v` | 1 | Logging level (0-3) |
| `--dry-run` | | False | Count pairs without connecting |
### Subcommands
```bash
# 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:
| Strategy | Method | Example output |
|----------|--------|----------------|
| Leet-speak | `leet_speak(word)` | `p@ssw0rd`, `p455w0rd` |
| Capitalisation | `capitalise_variants(word)` | `PASSWORD`, `Password`, `pAsSwOrD` |
| Suffix | `suffix_append(word)` | `password123`, `password@2025` |
| Prefix | `prefix_append(word)` | `!password`, `mypassword` |
| Keyboard-walk | `keyboard_walk(word)` | `qassword` (a→q) |
| Username patterns | `username_patterns(user, company)` | `john123`, `Doe1!`, `ACME2024!` |
| **Seasonal** (v1.1) | `seasonal_patterns(company)` | `Summer2024!`, `Winter25` |
| **Special-char wrap** (v1.1) | `special_char_wrap(word)` | `!@Password`, `Password!@` |
| Combine | `combine(word, strategies)` | chains any of the above |
| Smart (all-in-one) | `smart_generate(user, company)` | deduped, capped stream |
```python
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
```bash
# 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
```
```bash
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
```bash
# 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:
```bash
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
```bash
# 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
```bash
# 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:
| Area | Tests |
|------|-------|
| Lockout detector (sliding window, thread safety) | `test_lockout.py` |
| Password mutator strategies | `test_mutator.py` |
| New mutator strategies (seasonal, special-char) | `test_mutator_extended.py` |
| Proxy rotator (health-check, demotion) | `test_proxy.py` |
| Result & SessionReport dataclasses | `test_result.py` |
| SSH protocol mock | `test_protocols_ssh.py` |
| FTP protocol mock | `test_protocols_ftp.py` |
| HTTP Basic & Digest mocks | `test_protocols_http.py` |
---
## Wordlists
> **⚠️ The bundled `wordlists/` files are minimal smoke-test stubs.** Supply your own for real assessments.
### Recommended sources
| Wordlist | Size | Best For |
|----------|------|----------|
| `rockyou.txt` | ~14 M | General dictionary |
| `SecLists/Passwords/` | Various | Protocol-specific |
| `kaonashi.txt` | ~64 M | Advanced coverage |
| OSINT-derived | Variable | Targeted attacks |
```bash
# Use any external wordlist
python credattack.py ssh -t TARGET -u admin -P /opt/wordlists/rockyou.txt
```
---
## Project Structure
```
credential-attacks-toolkit/
├── credattack.py # Thin shim -> credattack.cli:app (source-checkout usage)
├── 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/
│ ├── cli.py # CLI (Typer) — packaged, backs the console script
│ ├── 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
├── attacks/ # Standalone single-file tools (predate credattack/;
│ └── *.py # kept for scripts not yet ported: JWT cracking,
│ # WAF detection, timing-based user enumeration)
├── utils/
│ └── credential_utils.py # Shared helpers for the attacks/ scripts
├── 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)
| Password Type | Dictionary | Smart Mode | Spray (common) |
|---------------|-----------|------------|----------------|
| 4 chars | ~90% | ~95% | ~60% |
| 6 chars | ~65% | ~75% | ~25% |
| 8 chars mixed | ~15% | ~25% | ~5% |
| 10+ chars complex | <5% | <5% | <1% |
---
## Contributing
See [CONTRIBUTING.md](https://github.com/amibhai/credential-attacks-toolkit/blob/main/CONTRIBUTING.md).
Please open an issue before submitting large PRs.
All contributions must adhere to the ethical use policy in [SECURITY.md](https://github.com/amibhai/credential-attacks-toolkit/blob/main/SECURITY.md).
---
**Use responsibly. Test ethically. Stay legal.**