Metadata-Version: 2.4
Name: perry-spies
Version: 1.0.3
Summary: Comprehensive Local Codebase Security & Quality Analyzer
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi==0.115.6
Requires-Dist: uvicorn[standard]==0.34.0
Requires-Dist: pydantic==2.10.5
Requires-Dist: pydantic-settings==2.7.1
Requires-Dist: sqlalchemy[asyncio]==2.0.36
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: alembic==1.14.0
Requires-Dist: httpx==0.28.1
Requires-Dist: beautifulsoup4==4.12.3
Requires-Dist: dnspython==2.7.0
Requires-Dist: PyJWT==2.10.1
Requires-Dist: bcrypt==4.2.1
Requires-Dist: email-validator==2.2.0
Requires-Dist: groq==0.13.1
Requires-Dist: python-dotenv==1.0.1
Requires-Dist: gitpython==3.1.43
Requires-Dist: playwright==1.62.0
Requires-Dist: esprima==4.0.1
Requires-Dist: tree-sitter==0.26.0
Requires-Dist: tree-sitter-language-pack==1.14.3

<p align="center">
  <img src="https://raw.githubusercontent.com/aayushhh-operator/perry/master/logo.png" alt="perry-spies" width="400"/>
</p>

# perry-spies

`perry-spies` is a powerful, lightweight Python package that provides comprehensive local static application security testing (SAST) and live web fuzzing features:

*   **Local Repository Scanning**: Multi-language AST-based parsing, hardcoded secret discovery, and dependency advisory checking.
*   **Live Web Fuzzing**: On-demand custom HTTP request validation, fuzzing suite attacks (SQLi, XSS, Path Traversal, Cmd Injection), and reporting.

You can run `perry-spies` inside your terminal for quick local audits, integrate it as a CI/CD gate in GitHub Actions/GitLab, or use its underlying services directly in your Python applications.

---

## More About perry-spies

At a granular level, `perry-spies` consists of the following key CLI subcommands and internal services:

| Component | Description |
| :--- | :--- |
| **`perry scan`** | Scans a local repository or directory for secrets, code quality issues, and dependency vulnerabilities. |
| **`perry custom-test`** | Sends on-demand attack vectors (shorthand or JSON schema) to a live URL and returns detailed findings. |
| **`perry.services.sast_engine`** | AST-based static analysis engine natively parsing Python and JS/TS patterns. |
| **`perry.services.risk_engine`** | Deterministic 5-factor risk scoring engine that bands repository threats from minimal to critical. |

Usually, `perry-spies` is used either as:
1. A fast, local pre-commit hook or security gate in CI/CD pipelines.
2. A lightweight fuzzer to quickly test specific live web endpoints for common injection vulnerabilities.

---

## Key Features

### AST-Based SAST
Rather than searching for naive regex patterns, `perry-spies` uses abstract syntax tree (AST) parsers (leveraging `tree-sitter` for polyglot support) to understand actual code structure. This flags genuine issues like unsafe SQL string concatenations and dangerous evaluations while keeping false positives low.

### Intelligent Secret Hygiene
The secret scanner matches credentials against high-entropy patterns. It automatically cross-references discovered secrets with your repository's `.gitignore`. Files that are ignored are flagged as low-severity *hygiene* logs, while unignored secrets generate active security alerts.

### Fully Local Dependency Advisory
It extracts dependencies from manifests (like `package.json`, `requirements.txt`, etc.) and performs reachability analysis. It queries OSV.dev advisories to check if vulnerable libraries are imported and actually used in execution paths.

### Live Fuzzing Preset Attacks
Using the `custom-test` subcommand, you can run pre-packaged test suites mimicking common attacks:
*   **Reflected XSS**: Identifies if unescaped markers reflect into the DOM.
*   **SQL Injection**: Probes inputs with database error-triggering and boolean payloads.
*   **Path Traversal**: Tests local file inclusion against system structures like `/etc/passwd`.
*   **Command Injection**: Traces system command outcomes using canary echo execution.

---

## Installation

Install the package directly from PyPI:

```bash
pip install perry-spies
```

### Local Development Installation
For developers wishing to extend or test `perry-spies` locally:

```bash
git clone https://github.com/aayushhh-operator/perry.git
cd perry/backend
pip install -e .
```

---

## Getting Started

### Scan the current directory
```bash
perry scan
```

### Scan a specific folder and fail if high/critical issues are found
```bash
perry scan /path/to/project --fail-on high
```

### Run the default fuzzing suite against a live site (with authorization)
```bash
perry custom-test --url https://perryspies.vercel.app/ --authorized
```

### Export definitive logs to a JSON file
```bash
perry scan --json report.json
```

---

## License

`perry-spies` is distributed under the MIT license.
