Metadata-Version: 2.5
Name: pyshield-security
Version: 0.2.0
Summary: Open-source developer-focused security analysis platform for Python projects.
Project-URL: Homepage, https://github.com/ZN-Forge/pyshield
Project-URL: Repository, https://github.com/ZN-Forge/pyshield
Project-URL: Issues, https://github.com/ZN-Forge/pyshield/issues
Project-URL: Documentation, https://github.com/ZN-Forge/pyshield#readme
Author-email: ZN-Forge <oss@zn-forge.org>
License: MIT
License-File: LICENSE
Keywords: ast,pyshield,pyshield-security,scanner,security,static-analysis,vulnerability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.7.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# PyShield

[![CI](https://github.com/ZN-Forge/pyshield/actions/workflows/ci.yml/badge.svg)](https://github.com/ZN-Forge/pyshield/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/pyshield-security.svg)](https://pypi.org/project/pyshield-security/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python: 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/)
[![Managed with uv](https://img.shields.io/badge/managed%20with-uv-blueviolet.svg)](https://docs.astral.sh/uv/)

**PyShield** is a developer-focused, open-source static security analysis platform for Python projects, maintained under the [**ZN-Forge**](https://github.com/ZN-Forge) organization.

Its primary purpose is to help developers identify potential security vulnerabilities in their code before reaching production through fast, deterministic AST analysis.

---

> [!NOTE]
> **Current Status: Version 0.2.0 (Core Engine, Injection, Secrets, Cryptography, Configuration & Dependencies)**
> PyShield v0.2.0 delivers a complete deterministic security suite: AST-based static analysis, injection prevention (`PS10x`), secret masking (`PS20x`), cryptography auditing (`PS30x`), configuration security (`PS70x`), and dependency vulnerability & pinning analysis (`PS80x`) powered by the OSV database with offline support. Future capabilities (SARIF export, React UI, etc.) are planned for upcoming releases.

---

## Core Philosophy

1. **Deterministic-First**: Security detection is powered primarily by deterministic AST analysis and strict rules. Findings are verifiable and reproducible.
2. **Local-First & Privacy-Focused**: Source code is analyzed entirely on your local machine and is never transmitted to external services.
3. **Secret Protection by Design**: Detected secret values and key material are masked in terminal reports and findings to prevent credential exposure.
4. **Core Decoupling**: The static security analysis engine is strictly decoupled from presentation, web server, and persistence layers.
5. **Minimal Dependencies**: The core analysis leverages Python's built-in `ast` and standard library to remain fast, lightweight, and maintainable without heavy external HTTP or dependency frameworks.
6. **Zero False-Positive Focus**: Rules are designed conservatively to highlight high-confidence security hazards without flooding developers with noise.

---

## Supported Rules

### Execution & Code Injection (Phase 1)
| Rule ID | Name | Severity | CWE | Description |
| :--- | :--- | :--- | :--- | :--- |
| **`PS101`** | Dangerous `eval()` usage | `CRITICAL` | CWE-95 | Detects calls to built-in `eval()`, preventing dynamic code execution risks. |
| **`PS102`** | Dangerous `exec()` usage | `CRITICAL` | CWE-95 | Detects calls to built-in `exec()`, preventing dynamic statement execution vulnerabilities. |
| **`PS103`** | Use of `os.system()` | `HIGH` | CWE-78 | Detects calls to `os.system()` which execute commands via shell strings. |
| **`PS104`** | Unsafe `subprocess` execution | `HIGH` | CWE-78 | Detects subprocess execution calls configured with `shell=True`. |

### Secret & Key Material Detection (Phase 2)
| Rule ID | Name | Severity | CWE | Description |
| :--- | :--- | :--- | :--- | :--- |
| **`PS201`** | Hardcoded Secret / Credential | `HIGH` | CWE-798 | Detects hardcoded passwords, tokens, secrets, and API keys with entropy filtering and placeholder exclusion. |
| **`PS202`** | Private Key Material | `CRITICAL` | CWE-321 | Detects hardcoded RSA, EC, DSA, and OpenSSH private key PEM headers and content. |
| **`PS203`** | High-Confidence API Token | `HIGH` | CWE-798 | Detects provider-specific tokens (AWS, GitHub classic/fine-grained, Slack, Google, Stripe) using strict patterns. |

### Cryptographic Analysis (Phase 2)
| Rule ID | Name | Severity | CWE | Description |
| :--- | :--- | :--- | :--- | :--- |
| **`PS301`** | Weak Hash Algorithm | `MEDIUM` | CWE-328 | Detects insecure MD5 and SHA-1 hashing via `hashlib` (exempts `usedforsecurity=False`). |
| **`PS302`** | Insecure Cryptographic Algorithm | `HIGH` | CWE-327 | Detects broken legacy ciphers (DES, 3DES, Blowfish, ARC4) in `cryptography` and PyCryptodome. |
| **`PS303`** | Insecure Randomness | `HIGH` | CWE-338 | Detects use of standard pseudo-random `random` module in security-sensitive contexts (tokens, salts, keys, auth). |

### Configuration Security (Phase 3)
| Rule ID | Name | Severity | CWE | Description |
| :--- | :--- | :--- | :--- | :--- |
| **`PS701`** | Debug Mode Enabled | `HIGH` | CWE-489 | Detects `DEBUG = True` enabled in configuration settings, exposing internal state and traces. |
| **`PS702`** | Insecure TLS Verification | `HIGH` | CWE-295 | Detects HTTP client calls disabling TLS certificate verification (`verify=False`). |
| **`PS703`** | Insecure Cookie Configuration | `MEDIUM` | CWE-614 | Detects disabled secure cookie transmission (`SESSION_COOKIE_SECURE = False`, etc.). |
| **`PS704`** | Insecure Host / Origin Wildcard | `HIGH` | CWE-346 | Detects wildcard host/CORS origins (`ALLOWED_HOSTS = ["*"]`, `CORS_ALLOW_ALL_ORIGINS = True`). |

### Dependency Security (Phase 3)
| Rule ID | Name | Severity | CWE | Description |
| :--- | :--- | :--- | :--- | :--- |
| **`PS801`** | Known Vulnerable Dependency | `HIGH` | CWE-1395 | Identifies dependencies with known published vulnerabilities via the OSV database. |
| **`PS802`** | Unpinned Dependency | `MEDIUM` | CWE-1104 | Detects dependencies declared without meaningful version constraints in `requirements.txt` / `pyproject.toml`. |

---

## Supported Dependency Sources

PyShield automatically discovers and analyzes the following dependency sources:
- **`requirements.txt`** (and `requirements*.txt`): Line-by-line PEP 508 parsing with comment and environment marker support.
- **`pyproject.toml`**: Standard PEP 621 `[project.dependencies]`, `[project.optional-dependencies]`, and `[dependency-groups]`.
- **`uv.lock`**: Precise resolved version verification (`uv.lock` is treated as the authoritative resolved source and is exempt from unpinned alerts).

---

## Installation

PyShield can be installed from PyPI using `pip` or `uv`:

```bash
# Using pip
pip install pyshield-security

# Using uv
uv add pyshield-security

# Or as a global CLI tool using uv:
uv tool install pyshield-security
```

> [!NOTE]
> The PyPI distribution package name is **`pyshield-security`**. The command-line command is **`pyshield`**, and the Python import package is **`pyshield`**:
> ```bash
> pyshield --version
> ```
> ```python
> import pyshield
> ```

---

## Development Setup

For local development or contributing, clone the repository and synchronize the isolated virtual environment using [`uv`](https://docs.astral.sh/uv/):

### Prerequisites
- Python 3.11 or higher
- `uv` package manager

### Setup
```bash
git clone https://github.com/ZN-Forge/pyshield.git
cd pyshield
uv sync
```

This creates a project-local `.venv/` containing all runtime and development dependencies locked in `uv.lock`.

---

## CLI Usage

### Check Version
```bash
# Direct CLI command (if installed via pip or uv tool):
pyshield --version

# Or inside the local development environment:
uv run pyshield --version
```

### Scan Current Directory
```bash
uv run pyshield scan .
```

### Scan Specific Directory or File
```bash
uv run pyshield scan src/
uv run pyshield scan app/main.py
```

### CLI Options

```bash
Usage: pyshield scan [OPTIONS] [PATHS]...

Arguments:
  [PATHS]...                    One or more paths to scan (default: current directory)

Options:
  --fail-on [LOW|MEDIUM|HIGH|CRITICAL]
                                Minimum severity to trigger non-zero exit code [default: LOW]
  -e, --exclude TEXT            Additional glob patterns or directories to exclude
  -d, --disable-rule TEXT       Rule ID to disable (e.g. -d PS101)
  --enable-rule TEXT            Explicit rule ID to run (e.g. --enable-rule PS103)
  --offline                     Run in offline mode without querying external vulnerability databases
  --help                        Show help message and exit
```

### Exit Codes
- `0`: Scan completed successfully; no findings at or above configured failure threshold.
- `1`: Security findings detected at or above configured failure threshold.
- `2`: Fatal error (target path not found, or all target files failed parsing).

---

## Development & Quality Gates

PyShield enforces strict quality gates before any code is merged:

```bash
# Run tests with coverage
uv run pytest --cov=pyshield --cov-report=term-missing

# Run Ruff linter
uv run ruff check .

# Run Ruff format check
uv run ruff format --check .

# Run strict type checking
uv run mypy src
```

---

## Planned Architecture (Future Phases)

The following capabilities are deliberately planned for subsequent phases:

- **Phase 1 (Completed)**: Core static analysis engine, rule registry, injection rules (`PS101`–`PS104`), CLI, and terminal reporter.
- **Phase 2 (Completed)**: Secret detection engine (`PS201`–`PS203`) and Cryptography rules (`PS301`–`PS303`) with zero leakage protection.
- **Phase 3 (Completed)**: Dependency vulnerability scanning (`PS801`), pinning analysis (`PS802`), and Configuration security rules (`PS701`–`PS704`) with offline mode.
- **Phase 4+**: Standard SARIF, JSON, and Markdown export formats.
- **Phase 5+**: Optional Local AI analysis layer (via Ollama / llama.cpp) to explain and contextualize deterministic findings.
- **Phase 6+**: Local Web UI (React + TypeScript + Vite + Tailwind CSS) with FastAPI backend and SQLite persistence.
- **Phase 7+**: Comprehensive product/documentation website on GitHub Pages and contributor ecosystem.

---

## License

This project is licensed under the [MIT License](LICENSE).
