pyshield-security 0.1.0__tar.gz

pyshield_security-0.1.0/.gitignore

@@ -0,0 +1,68 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Code quality
+.ruff_cache/
+.mypy_cache/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

pyshield_security-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

pyshield_security-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-06
+
+### Added
+- **Core Static Security Analysis Engine**:
+  - Deterministic Python `ast`-based analyzer with graceful syntax error and decode recovery.
+  - Safe recursive file discovery respecting ignore patterns (`.git`, `.venv`, `__pycache__`) and symlink cycles.
+  - Extensible `RuleRegistry` and `BaseRule` architecture.
+  - Decoupled terminal reporting using `rich`.
+  - Developer-friendly CLI via `typer` (`pyshield scan`, `pyshield --version`).
+  - Standardized exit codes (`0` clean, `1` findings detected, `2` fatal error).
+- **Execution & Injection Security Rules (Phase 1)**:
+  - `PS101`: Dangerous `eval()` usage detection (CWE-95).
+  - `PS102`: Dangerous `exec()` usage detection (CWE-95).
+  - `PS103`: Dangerous `os.system()` usage detection (CWE-78).
+  - `PS104`: Unsafe `subprocess` execution with `shell=True` (CWE-78).
+- **Secret Detection & Cryptography Analysis Rules (Phase 2)**:
+  - `PS201`: Hardcoded Secret / Credential detection with contextual identifier matching, Shannon entropy analysis, and placeholder filtering.
+  - `PS202`: Private Key Material detection for RSA, EC, DSA, and OpenSSH private key PEM blocks.
+  - `PS203`: High-confidence API Token detection with specific patterns for AWS, GitHub (classic and fine-grained PATs), Slack, Google, and Stripe.
+  - `PS301`: Weak Cryptographic Hash detection for MD5 and SHA-1 via `hashlib` (properly exempts `usedforsecurity=False`).
+  - `PS302`: Insecure Cryptographic Algorithm detection for broken legacy ciphers (DES, 3DES, Blowfish, ARC4) across `cryptography` and `Crypto.Cipher`.
+  - `PS303`: Insecure Randomness detection for pseudo-random standard library `random` module usage in security-sensitive scopes (tokens, passwords, keys, salts).
+  - Shared secrets utility module (`secrets_utils.py`) with Shannon entropy, placeholder recognition, and sensitive token masking.
+  - Strict secret leakage prevention guaranteeing detected secrets never appear in finding messages, descriptions, snippets, logs, or terminal reports.
+- **Testing & Quality**:
+  - Complete test suite with 155 unit and integration tests achieving >94% line coverage.
+  - Strict typing (Mypy strict mode) and Ruff linting/formatting.

pyshield_security-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,35 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and also applies when an individual is representing the project or its community in public spaces.
+
+## Contact
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leadership at `conduct@zn-forge.org`. All complaints will be reviewed and investigated promptly and fairly.

pyshield_security-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing to PyShield
+
+Thank you for your interest in contributing to PyShield!
+
+PyShield is an open-source security analysis platform maintained under the **ZN-Forge** organization. We welcome contributions from developers of all backgrounds.
+
+## Development Principles
+
+1. **Deterministic-first**: Security rules must be deterministic, accurate, and have minimal false positives.
+2. **Local-first & Privacy-conscious**: Source code must never leave the local environment by default.
+3. **Core Decoupling**: Core analysis must remain completely decoupled from presentation, API, and database layers.
+4. **Minimal Dependencies**: Do not add dependencies unless strictly required.
+5. **Rigorous Quality**: Every new feature or rule must include unit tests, type annotations, and pass all quality gates.
+
+## Development Setup
+
+We use [`uv`](https://docs.astral.sh/uv/) for project and dependency management.
+
+### 1. Clone the repository
+```bash
+git clone https://github.com/ZN-Forge/pyshield.git
+cd pyshield
+```
+
+### 2. Set up isolated environment
+```bash
+uv sync
+```
+
+This creates a local `.venv/` and installs all runtime and development dependencies locked in `uv.lock`.
+
+### 3. Run Quality Gates
+Before submitting a PR, make sure all quality checks pass:
+
+```bash
+# Run tests with coverage
+uv run pytest --cov=pyshield --cov-report=term-missing
+
+# Run linter
+uv run ruff check .
+
+# Run code formatter check
+uv run ruff format --check .
+
+# Run type checker
+uv run mypy src
+```
+
+## Adding a Security Rule
+
+When contributing a new rule:
+1. Choose an appropriate ID (e.g., `PS1xx` for Execution/Injection).
+2. Implement the rule in `src/pyshield/rules/builtin/` inheriting from `BaseRule`.
+3. Provide comprehensive positive tests (detect vulnerable pattern), negative tests (safe patterns), and edge cases (avoiding false positives).
+4. Register the rule in `src/pyshield/core/registry.py`.
+5. Update documentation and rule references.

pyshield_security-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZN-Forge
+
+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 restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, 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 WARRANTIES OF MERCHANTABILITY,
+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, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyshield_security-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.5
+Name: pyshield-security
+Version: 0.1.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.1.0 (Core Engine, Injection, Secrets & Cryptography)**
+> PyShield v0.1.0 provides a fast, deterministic static analysis engine, rule registry, code execution/injection rules, secret detection, and cryptography security analysis. All detected secrets are automatically masked in output to prevent sensitive data leakage. Future capabilities (SARIF export, dependency scanning, 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` standard library to remain fast, lightweight, and maintainable.
+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). |
+
+---
+
+## 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)
+  --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+**: Dependency vulnerability scanning (`PS8xx`) and Framework-specific rules (Django, FastAPI, Flask).
+- **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).

pyshield_security-0.1.0/README.md

@@ -0,0 +1,185 @@
+# 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.1.0 (Core Engine, Injection, Secrets & Cryptography)**
+> PyShield v0.1.0 provides a fast, deterministic static analysis engine, rule registry, code execution/injection rules, secret detection, and cryptography security analysis. All detected secrets are automatically masked in output to prevent sensitive data leakage. Future capabilities (SARIF export, dependency scanning, 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` standard library to remain fast, lightweight, and maintainable.
+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). |
+
+---
+
+## 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)
+  --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+**: Dependency vulnerability scanning (`PS8xx`) and Framework-specific rules (Django, FastAPI, Flask).
+- **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).

pyshield_security-0.1.0/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Supported Versions
+
+PyShield takes security seriously. Security updates are applied to the active development version.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability within PyShield, please report it responsibly.
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Instead, please report security issues via GitHub Private Vulnerability Reporting on the repository, or by emailing the maintainers at:
+
+`security@zn-forge.org`
+
+Include as much of the following details as possible:
+- Description of the vulnerability and its potential impact
+- Steps to reproduce the vulnerability (proof of concept code or configuration)
+- Environment details (Python version, PyShield version, OS)
+- Any proposed remediation or mitigations
+
+## Response Process
+
+1. You will receive an acknowledgment of your report within 48 hours.
+2. The PyShield maintainers will evaluate the report and verify the issue.
+3. If confirmed, a fix will be prepared in a private fork and tested thoroughly.
+4. A patched release will be issued alongside a public security advisory crediting the reporter (if desired).

pyshield_security-0.1.0/docs/README.md

@@ -0,0 +1,4 @@
+# PyShield Documentation
+
+This directory will host documentation sources for PyShield.
+Comprehensive GitHub Pages documentation is planned for a subsequent release.

pyshield_security-0.1.0/examples/README.md

@@ -0,0 +1,3 @@
+# PyShield Examples
+
+This directory contains reference examples for scanning with PyShield.