# ShadowGate
[](https://www.python.org/)
[](LICENSE)
[](https://github.com/alimghmi/ShadowGate)
ShadowGate is a fast, async-driven web reconnaissance and exposure scanner for detecting admin panels, login interfaces, and misconfigured endpoints across single or multiple targets — built for professional penetration testers and security researchers.
> ⚠️ **Authorized testing only.** You must have explicit permission to scan any target.
---
## Overview
ShadowGate combines concurrency, user-agent rotation, proxy routing, and response classification to efficiently identify potentially exposed web interfaces.
It provides structured output (NDJSON/JSON/CSV) suitable for pipelines and automation.
Key features:
- Async scanning engine for high-speed probing.
- Multiple routing modes: direct, proxy list, Tor.
- Customizable wordlists, user-agents, and status-code filters.
- Progress bar and interactive output using **Rich**.
- Machine-readable formats: `ndjson`, `json`, `csv`.
- Legal disclaimers and safety controls to discourage misuse.
---
<!-- ## Badges & Demo
--- -->
## Installation
```bash
git clone https://github.com/alimghmi/ShadowGate.git
cd ShadowGate
pip install -e .
```
Or (future):
```bash
pip install shadowgate
```
Requirements: **Python 3.10+**
---
## Quickstart
Basic CLI syntax:
```bash
python -m shadowgate.cli [GLOBAL FLAGS] COMMAND [OPTIONS]
```
Example:
```bash
python -m shadowgate.cli scan -t https://example.com --assume-legal
```
### Global options
- `-v`, `-vv` — Increase verbosity (info/debug).
- `--quiet` — Suppress non-error logs.
- `--version` — Show version and exit.
---
## Commands
### `scan`
Probe target(s) for exposed admin/login panels.
Examples:
```bash
# Single target
shadowgate scan -t example.com --assume-legal
# Multiple targets
shadowgate scan --targets targets.txt --assume-legal
# Custom wordlist and user agents
shadowgate scan -t example.com --wordlist common.txt --random-ua --assume-legal
# Save results to file (JSON)
shadowgate scan -t example.com --out json --output results.json --assume-legal
# Route traffic via Tor
shadowgate scan -t example.com --tor --assume-legal
```
Options summary (high level):
- `-t, --target` : Single URL or domain
- `--targets` : File with one target per line
- `--wordlist` : Override built-in wordlist
- `--useragents` : Override built-in user-agents
- `--proxies` / `--proxy` : File or inline proxy(s)
- `--tor` : Route traffic via Tor
- `--status-codes` : Acceptable response codes (e.g., `200,3xx,401-403`)
- `--rps` : Requests per second (default: 10)
- `--concurrency` : Number of in-flight requests
- `--timeout` : Per-request timeout (seconds)
- `--retries` : Retry attempts
- `--follow-redirects` : Follow HTTP redirects
- `--random-ua` : Rotate User-Agent headers
- `--insecure` : Disable TLS verification (warning shown)
- `--out` : Output format (`ndjson`, `json`, `csv`, `table`)
- `--output` : Save results to file
- `--assume-legal` : Confirm you have authorization
---
## Output formats
- `ndjson` — Newline-delimited JSON (recommended for pipelines)
- `json` — Pretty JSON
- `csv` — Spreadsheet-compatible
- `table` — Human-readable Rich table
Example NDJSON line:
```json
{"url":"https://example.com/admin/","status":200,"ok":true,"error":null,"elapsed":0.123}
```
---
## Logging & Debugging
Control verbosity with `-v`:
```bash
# Info-level logs
shadowgate -v scan -t example.com --assume-legal
# Debug with tracebacks
shadowgate -vv scan -t example.com --assume-legal
```
Logs and progress/status output are written to STDERR; scan results are emitted to STDOUT (so they can be piped or saved).
---
## Architecture (brief)
- `cli.py` — Typer-based CLI with Rich output and logging controls.
- `engine.py` — Asynchronous scanning engine handling requests, rate-limiting, and result collection.
- `utils.py` — Wordlists, user-agents, helper utilities.
- `wordlists/` — Default wordlists and payloads.
The CLI isolates control-plane logs (stderr) from data-plane output (stdout), enabling safe automation and piping.
---
## Legal & Ethics
ShadowGate is intended **for authorized security testing and research only**. Unauthorized scanning may be illegal and unethical. Always obtain written permission before testing.
Use the bundled legal command to show the short disclaimer:
```bash
shadowgate legal
```
---
## Contributing
Contributions are welcome.
1. Fork the repository
2. Create a branch (`git checkout -b feature/your-feature`)
3. Open a Pull Request
Please include tests and documentation for new features.
---
## License
MIT License © Ali Moghimi
See `LICENSE` for details.
---
## Acknowledgements & References
- Inspired by tools like `ffuf`, `dirsearch`, and `nmap`.
- Built with: [Typer](https://typer.tiangolo.com), [Rich](https://github.com/Textualize/rich)
---
Raw data
{
"_id": null,
"home_page": null,
"name": "shadowgate",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "security, pentest, admin-finder, recon, httpx, cli",
"author": "Ali Moghimi",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b1/5a/db1bf88f6b3ea30ffc071723bdfdc336d75b14de57b92463273422c24fa1/shadowgate-0.1.1.tar.gz",
"platform": null,
"description": "# ShadowGate\n\n[](https://www.python.org/)\n[](LICENSE)\n[](https://github.com/alimghmi/ShadowGate)\n\nShadowGate is a fast, async-driven web reconnaissance and exposure scanner for detecting admin panels, login interfaces, and misconfigured endpoints across single or multiple targets \u2014 built for professional penetration testers and security researchers.\n\n> \u26a0\ufe0f **Authorized testing only.** You must have explicit permission to scan any target.\n\n---\n\n## Overview\n\nShadowGate combines concurrency, user-agent rotation, proxy routing, and response classification to efficiently identify potentially exposed web interfaces. \nIt provides structured output (NDJSON/JSON/CSV) suitable for pipelines and automation.\n\nKey features:\n- Async scanning engine for high-speed probing.\n- Multiple routing modes: direct, proxy list, Tor.\n- Customizable wordlists, user-agents, and status-code filters.\n- Progress bar and interactive output using **Rich**.\n- Machine-readable formats: `ndjson`, `json`, `csv`.\n- Legal disclaimers and safety controls to discourage misuse.\n\n---\n\n<!-- ## Badges & Demo\n\n\n\n--- -->\n\n## Installation\n\n```bash\ngit clone https://github.com/alimghmi/ShadowGate.git\ncd ShadowGate\npip install -e .\n```\n\nOr (future):\n\n```bash\npip install shadowgate\n```\n\nRequirements: **Python 3.10+**\n\n---\n\n## Quickstart\n\nBasic CLI syntax:\n\n```bash\npython -m shadowgate.cli [GLOBAL FLAGS] COMMAND [OPTIONS]\n```\n\nExample:\n\n```bash\npython -m shadowgate.cli scan -t https://example.com --assume-legal\n```\n\n### Global options\n\n- `-v`, `-vv` \u2014 Increase verbosity (info/debug).\n- `--quiet` \u2014 Suppress non-error logs.\n- `--version` \u2014 Show version and exit.\n\n---\n\n## Commands\n\n### `scan`\n\nProbe target(s) for exposed admin/login panels.\n\nExamples:\n\n```bash\n# Single target\nshadowgate scan -t example.com --assume-legal\n\n# Multiple targets\nshadowgate scan --targets targets.txt --assume-legal\n\n# Custom wordlist and user agents\nshadowgate scan -t example.com --wordlist common.txt --random-ua --assume-legal\n\n# Save results to file (JSON)\nshadowgate scan -t example.com --out json --output results.json --assume-legal\n\n# Route traffic via Tor\nshadowgate scan -t example.com --tor --assume-legal\n```\n\nOptions summary (high level):\n\n- `-t, --target` : Single URL or domain\n- `--targets` : File with one target per line\n- `--wordlist` : Override built-in wordlist\n- `--useragents` : Override built-in user-agents\n- `--proxies` / `--proxy` : File or inline proxy(s)\n- `--tor` : Route traffic via Tor\n- `--status-codes` : Acceptable response codes (e.g., `200,3xx,401-403`)\n- `--rps` : Requests per second (default: 10)\n- `--concurrency` : Number of in-flight requests\n- `--timeout` : Per-request timeout (seconds)\n- `--retries` : Retry attempts\n- `--follow-redirects` : Follow HTTP redirects\n- `--random-ua` : Rotate User-Agent headers\n- `--insecure` : Disable TLS verification (warning shown)\n- `--out` : Output format (`ndjson`, `json`, `csv`, `table`)\n- `--output` : Save results to file\n- `--assume-legal` : Confirm you have authorization\n\n---\n\n## Output formats\n\n- `ndjson` \u2014 Newline-delimited JSON (recommended for pipelines)\n- `json` \u2014 Pretty JSON\n- `csv` \u2014 Spreadsheet-compatible\n- `table` \u2014 Human-readable Rich table\n\nExample NDJSON line:\n\n```json\n{\"url\":\"https://example.com/admin/\",\"status\":200,\"ok\":true,\"error\":null,\"elapsed\":0.123}\n```\n\n---\n\n## Logging & Debugging\n\nControl verbosity with `-v`:\n\n```bash\n# Info-level logs\nshadowgate -v scan -t example.com --assume-legal\n\n# Debug with tracebacks\nshadowgate -vv scan -t example.com --assume-legal\n```\n\nLogs and progress/status output are written to STDERR; scan results are emitted to STDOUT (so they can be piped or saved).\n\n---\n\n## Architecture (brief)\n\n- `cli.py` \u2014 Typer-based CLI with Rich output and logging controls.\n- `engine.py` \u2014 Asynchronous scanning engine handling requests, rate-limiting, and result collection.\n- `utils.py` \u2014 Wordlists, user-agents, helper utilities.\n- `wordlists/` \u2014 Default wordlists and payloads.\n\nThe CLI isolates control-plane logs (stderr) from data-plane output (stdout), enabling safe automation and piping.\n\n---\n\n## Legal & Ethics\n\nShadowGate is intended **for authorized security testing and research only**. Unauthorized scanning may be illegal and unethical. Always obtain written permission before testing.\n\nUse the bundled legal command to show the short disclaimer:\n\n```bash\nshadowgate legal\n```\n\n---\n\n## Contributing\n\nContributions are welcome.\n\n1. Fork the repository\n2. Create a branch (`git checkout -b feature/your-feature`)\n3. Open a Pull Request\n\nPlease include tests and documentation for new features.\n\n---\n\n## License\n\nMIT License \u00a9 Ali Moghimi \nSee `LICENSE` for details.\n\n---\n\n## Acknowledgements & References\n\n- Inspired by tools like `ffuf`, `dirsearch`, and `nmap`.\n- Built with: [Typer](https://typer.tiangolo.com), [Rich](https://github.com/Textualize/rich)\n\n---\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Admin panel finder and directory brute-forcer (async HTTPX/Typer).",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/yourusername/shadowgate",
"Issues": "https://github.com/yourusername/shadowgate/issues",
"Repository": "https://github.com/yourusername/shadowgate"
},
"split_keywords": [
"security",
" pentest",
" admin-finder",
" recon",
" httpx",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "64b75b2706aa5823400d6167b0412c1a6edfbd3addd0a5a6d0799a794bcc135a",
"md5": "8d43fceeb05557eae2ea559695800155",
"sha256": "caa4cd2b173d7bde76aac192383f84b2ceb6bb6acb69181d577ea7f79a425bba"
},
"downloads": -1,
"filename": "shadowgate-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8d43fceeb05557eae2ea559695800155",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 35673,
"upload_time": "2025-10-23T20:20:50",
"upload_time_iso_8601": "2025-10-23T20:20:50.288013Z",
"url": "https://files.pythonhosted.org/packages/64/b7/5b2706aa5823400d6167b0412c1a6edfbd3addd0a5a6d0799a794bcc135a/shadowgate-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b15adb1bf88f6b3ea30ffc071723bdfdc336d75b14de57b92463273422c24fa1",
"md5": "3ff13f5affd9da6a49293b6fb121215c",
"sha256": "9f84ad8829de77fa992167164bfdb81620f3c54de755fd9388451634f24998f7"
},
"downloads": -1,
"filename": "shadowgate-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "3ff13f5affd9da6a49293b6fb121215c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 40157,
"upload_time": "2025-10-23T20:20:51",
"upload_time_iso_8601": "2025-10-23T20:20:51.402446Z",
"url": "https://files.pythonhosted.org/packages/b1/5a/db1bf88f6b3ea30ffc071723bdfdc336d75b14de57b92463273422c24fa1/shadowgate-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 20:20:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "shadowgate",
"github_not_found": true,
"lcname": "shadowgate"
}
JSON
