Metadata-Version: 2.4
Name: hsignal-paramspy
Version: 0.1.0
Summary: The high-signal parameter discovery tool. Finds target-specific, production-used parameters from 10+ years of Wayback data.
Project-URL: Homepage, https://github.com/MenukaRisith/paramspy
Project-URL: Documentation, https://github.com/MenukaRisith/paramspy
Project-URL: Source, https://github.com/MenukaRisith/paramspy
Author-email: Menuka Risith <menuka.contact@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Menuka Risith Rupalal
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the software without limitation the rights to use, copy, sublicense, and/or sell copies of the software, and to permit persons to whom the software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT, WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, OUT TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR THE DEALINGS IN THE SOFTWARE.
License-File: LICENSE
Keywords: bug-bounty,hacking,parameter-discovery,recon,security
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.6.1
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: sqlite-utils>=3.35.0
Requires-Dist: typer[all]>=0.12.3
Requires-Dist: urllib3>=2.2.1
Description-Content-Type: text/markdown

# 🕵‍♂ paramspy: Smart Parameter Discovery Tool

### Stop Brute-Forcing Noise. Start Spying on Targets.

| Version | Python | License | Status |
| :---: | :---: | :---: | :---: |
| [![PyPI](https://img.shields.io/pypi/v/paramspy.svg)](https://pypi.org/project/paramspy/) | [![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) | [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) | *Ready for Bug Bounty* |

*paramspy* is an ultra-fast, high-signal reconnaissance tool that automates the discovery of hidden and target-specific parameters by analyzing *10+ years of Wayback Machine data*. It bypasses the time-wasting process of running massive, generic wordlists, providing you with a clean, actionable list of production-used parameters in seconds.

---

## ✨ Why paramspy is a Game Changer

Traditional parameter discovery methods suffer from a low signal-to-noise ratio, wasting time and often missing unique bugs.

| Feature | Generic Wordlists (e.g., 60k lines) | *paramspy (Targeted ~200-800 lines)* |
| :--- | :--- | :--- |
| *Source Data* | Random, common junk | *Target-specific* Wayback URLs (10+ years) |
| *Signal-to-Noise* | Low (Drowning in false positives) | *High* (Real, validated production parameters) |
| *Time Saved* | Minimal (Slow brute-force) | *Saves 15–45 minutes per target* |
| *Killer Feature* | None | Seamless *Gf-pattern integration* |
| *Performance* | Slow | *Instant* (Uses cache and clean list) |

---

## ⚡ Installation

paramspy is available on PyPI and supports Python 3.9+.

```bash
# 1. Install the package
pip install paramspy

# 2. Recommended: Ensure you have a fuzzer (like ffuf) and gf installed
# go install [github.com/ffuf/ffuf@latest](https://github.com/ffuf/ffuf@latest)
# go install [github.com/tomnomnom/gf@latest](https://github.com/tomnomnom/gf@latest)
```

---

## 📖 Usage & Examples
1. Basic Scan & Piping
The default mode outputs a clean list directly to stdout, perfect for piping into your favorite fuzzing tools.

```bash
# Get the high-signal parameter list for the target
paramspy shopify.com

# Pipe the clean list directly into ffuf
paramspy tesla.com | ffuf -u "[https://tesla.com/v1/api/FUZZ](https://tesla.com/v1/api/FUZZ)" -w - -mc 200

# Pipe the clean list into arjun
paramspy example.com > params.txt
arjun -u [https://example.com](https://example.com) -i params.txt
```

2. The Killer Feature: Gf-Pattern Tagging (JSON Output)
Use the --output json flag to get a structured output, and then use jq to filter parameters tagged for specific vulnerability classes (like redirect or xss).

```bash
# 1. Run scan and get structured JSON output
paramspy target.com --output json > results.json

# 2. Use jq to extract only parameters related to redirects (HIGH PRIORITY!)
# This is equivalent to running 'gf redirect' but on a target-specific wordlist.
cat results.json | jq '.parameters[] | select(.tags[] | contains("redirect")) | .param' -r

# Example Output (Gold for Open Redirects/SSRF)
# redirect_uri
# return_to
# callback
# next
```

3. Cache Management
`paramspy` uses a local SQLite cache (`~/.paramspy/cache/`) to make repeated scans instant.

```bash
# Check status of all cached domains
paramspy cache status

# Clear the cache for a specific domain
paramspy cache clear tesla.com

# Clear the entire cache
paramspy cache clear
```

---

## ⚙️ Core Technology

- **Asynchronous Fetching:** Uses `httpx` for fast, concurrent fetching from the Wayback CDX API.

- **Intelligent Parsing:** Robust regex and `urllib.parse` handle standard, matrix, and encoded parameters.

- **Reliable CLI:** Built with Typer and provides beautiful terminal output and progress bars via Rich.

- **Production Caching:** Uses SQLite for performance, integrity, and simple TTL management.

---

## 🤝 Contribution

We welcome contributions! The most valuable contribution is expanding the high-signal built-in wordlist (`paramspy/data/builtin_params.json`). If you found a unique, non-generic parameter that led to a successful bug bounty submission, please open a Pull Request to add it!

1. Fork the repository.
2. Create your feature branch (`git checkout -b feature/new-parser`).
3. Commit your changes (`git commit -am 'Feat: Add new regex for complex URLs'`).
4. Push to the branch (`git push origin feature/new-parser`).
5. Create a new Pull Request.

---

## 📜 License

Distributed under the MIT License. See `LICENSE` for more information.