Metadata-Version: 2.4
Name: perry-spies
Version: 1.1.0
Summary: Comprehensive Local Codebase Security & Quality Analyzer with deterministic code remediation
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1.0,>=0.115.6
Requires-Dist: uvicorn[standard]<1.0,>=0.34.0
Requires-Dist: pydantic<3.0,>=2.12
Requires-Dist: pydantic-settings<3.0,>=2.7.1
Requires-Dist: sqlalchemy[asyncio]<3.0,>=2.0.41
Requires-Dist: asyncpg>=0.30.0
Requires-Dist: alembic<2.0,>=1.14.0
Requires-Dist: httpx<1.0,>=0.28.1
Requires-Dist: beautifulsoup4<5.0,>=4.12.3
Requires-Dist: dnspython<3.0,>=2.7.0
Requires-Dist: PyJWT<3.0,>=2.10.1
Requires-Dist: bcrypt<6.0,>=4.2.1
Requires-Dist: email-validator<3.0,>=2.2.0
Requires-Dist: groq<2.0,>=0.13.1
Requires-Dist: python-dotenv<2.0,>=1.0.1
Requires-Dist: gitpython<4.0,>=3.1.43
Requires-Dist: esprima<5.0,>=4.0.1
Requires-Dist: tree-sitter<1.0,>=0.25.0
Requires-Dist: tree-sitter-language-pack<2.0,>=1.14.3
Requires-Dist: networkx>=3.1
Provides-Extra: browser
Requires-Dist: playwright>=1.49; extra == "browser"
Provides-Extra: dev
Requires-Dist: pytest>=8.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.26.0; extra == "dev"

<p align="center">
  <img src="https://i.postimg.cc/Pqvt3f8n/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 remediate`** | Proposes deterministic code fixes for what a scan finds, ordered by a heuristic search. Never modifies your files. |
| **`perry explain`** | Shows why one finding scored what it did and which fix template applies to it. |
| **`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.

### Deterministic Remediation — no LLM, no generated code
`perry remediate` proposes concrete fixes: parameterised queries, argument-list
`subprocess` calls, `textContent` instead of `innerHTML`, secrets moved to the
environment, narrowed exception handlers, dependency bumps to the lowest
version that clears every advisory. Every patch comes from a pre-audited
template with a golden test behind it, so perry can decline to fix something
but it cannot hallucinate broken code. Proposals are validated in an in-memory
sandbox — re-parsed, re-scanned, checked for regressions — and rendered as a
unified diff. **Your files are never modified.**

### Broad Vulnerability Coverage
44 fix templates spanning SQL and NoSQL injection, command injection, path
traversal, SSRF, SSTI, open redirect, the XSS family (DOM, reflected, React,
template filters), XXE, weak hashing, insecure randomness, disabled TLS
verification, hardcoded secrets, CSRF, CORS, cookie flags, error handling and
deployment hygiene. Run `perry templates` to see the full matrix, including the
handful of issue types that are manual-review by design and why.

### 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
```

### See proposed fixes (nothing is modified)
```bash
perry remediate
perry remediate --diff-out fix.patch   # write a `git apply`-able patch set
```

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

`--json` writes exactly one file, to exactly the path you give it. A plain
`perry scan` writes nothing at all.

---

## License

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