Merge branch 'main' of https://github.com/ParzivalHack/PySpector

Author: ParzivalHack

NOTICE.md

@@ -0,0 +1,14 @@
+## Repository Repurposed
+
+This repository has been **repurposed**.  
+Originally, it contained a small experimental script with no real usage or community activity.  
+
+As of 13/09/2025 (DD/MM/YYYY), the repository has been **reset and transformed** into a **new, professional project**: Pyspector, which is **completely different** from the original content.  
+
+The star count and forks have been preserved for continuity, but please note that they refer to the old repository state.  
+
+If you are here for **PySpector**, you are in the right place :)
+  
+The code, documentation, and roadmap you see now are **the new software**, actively maintained.  
+
+Final note: some forks of this repository may still contain the old code, but they are unrelated to the current project.

README.md

@@ -0,0 +1,133 @@
+# PySpector: An High-Performance Python and Rust SAST Framework
+
+![PySpector's version](https://img.shields.io/badge/PySpector%20version-0.1.0--beta-blue)
+
+PySpector is a static analysis security testing (SAST) Framework engineered for modern Python development workflows. It leverages a powerful Rust core to deliver high-speed, accurate vulnerability scanning, wrapped in a developer-friendly Python CLI. By compiling the analysis engine to a native binary, PySpector avoids the performance overhead of traditional Python-based tools, making it an ideal choice for integration into CI/CD pipelines and local development environments where speed is critical.
+
+The tool is designed to be both comprehensive and intuitive, offering a multi-layered analysis approach that goes beyond simple pattern matching to understand the structure and data flow of your application.
+
+
+
+## Getting Started
+
+### Prerequisites
+
+-   **Python**: Version 3.12 or lower (3.8+).
+-   **Rust**: The Rust compiler (`rustc`) and Cargo package manager are required. You can verify your installation by running `cargo --version`.
+
+### Installation
+
+1.  **Create a Virtual Environment**: It is highly recommended to install PySpector in a dedicated virtual environment.
+    ```bash
+    python3.12 -m venv venv
+    source venv/bin/activate
+    ```
+2.  **Install Build Dependencies**: PySpector uses `maturin` to build its Rust core.
+    ```bash
+    pip install maturin setuptools-rust
+    ```
+3.  **Install PySpector**: From the root of the project repository, install the package. This will compile the Rust core and install the Python wrapper.
+    ```bash
+    pip install .
+    ```
+
+## Key Features
+
+* **Multi-Layered Analysis Engine:** PySpector employs a sophisticated, multi-layered approach to detect a broad spectrum of vulnerabilities:
+
+* * **Regex-Based Pattern Matching:** Scans all files for specific patterns, ideal for identifying hardcoded secrets, insecure configurations in Dockerfiles, and weak settings in framework files.
+
+* * **Abstract Syntax Tree (AST) Analysis:** For Python files, the tool parses the code into an AST to analyze its structure. This enables precise detection of vulnerabilities tied to code constructs, such as the use of eval(), insecure deserialization with pickle, or weak hashing algorithms.
+
+* * **Inter-procedural Taint Analysis:** The engine builds a comprehensive call graph of the entire application to perform taint analysis. It tracks the flow of data from input sources (like web requests) to dangerous sinks (like command execution functions), allowing it to identify complex injection vulnerabilities with high accuracy.
+
+* **Comprehensive and Customizable Ruleset:** PySpector comes with 238 built-in rules that cover common vulnerabilities, including those from the OWASP Top 10. The rules are defined in a simple TOML format, making them easy to understand and extend.
+
+* **Versatile Reporting:** Generates clear and actionable reports in multiple formats, including a developer-friendly console output, JSON, HTML, and SARIF for seamless integration with other security tools and platforms.
+
+* **Efficient Baselining:** The interactive triage mode simplifies the process of establishing a security baseline, allowing teams to focus on new and relevant findings in each scan.
+
+## How It Works
+
+PySpector's hybrid architecture is key to its performance and effectiveness.
+
+* **Python CLI Orchestration:** The process begins with the Python-based CLI. It handles command-line arguments, loads the configuration and rules, and prepares the target files for analysis. For each Python file, it uses the native ast module to generate an Abstract Syntax Tree, which is then serialized to JSON.
+
+* **Invocation of the Rust Core:** The serialized ASTs, along with the ruleset and configuration, are passed to the compiled Rust core. The handoff from Python to Rust is managed by the pyo3 library.
+
+* **Parallel Analysis in Rust:** The Rust engine takes over and performs the heavy lifting. It leverages the rayon crate to execute file scans and analysis in parallel, maximizing the use of available CPU cores. It builds a complete call graph of the application to understand inter-file function calls, which is essential for the taint analysis module.
+
+* **Results and Reporting:** Once the analysis is complete, the Rust core returns a structured list of findings to the Python CLI. The Python wrapper then handles the final steps of filtering the results based on the severity threshold and the baseline file, and generating the report in the user-specified format.
+
+This architecture combines the best of both worlds: a flexible, user-friendly interface in Python and a high-performance, memory-safe analysis engine in Rust :)
+
+## Usage
+
+PySpector is operated through a straightforward command-line interface.
+
+### Running a Scan
+
+The primary command is `scan`, which can target a local file, a directory, or even a remote Git repository.
+
+```bash
+pyspector scan [PATH or --url REPO_URL] [OPTIONS]
+```
+
+## Examples:
+
+* **Scan a single file**
+```bash
+pyspector scan project/main.py
+```
+
+* **Scan a local directory and save the report as HTML:**
+```bash
+pyspector scan /path/to/your/project -o report.html -f html
+```
+
+* **Scan a public GitHub repository:**
+```bash
+pyspector scan --url https://github.com/username/repo.git
+```
+
+## Triaging and Baselining Findings
+<img width="871" height="950" alt="image" src="https://github.com/user-attachments/assets/5f31c2fc-9216-408e-975f-a1652c6bbdc7" />
+
+PySpector includes an interactive triage mode to help manage and baseline findings. This allows you to review issues and mark them as "ignored" so they don't appear in future scans.
+
+* **Generate a JSON report:**
+```bash
+pyspector scan /path/to/your/project -o report.json -f json
+```
+
+* **Start the triage TUI:**
+```bash
+pyspector triage report.json
+```
+
+Inside the TUI, you can navigate with the arrow keys, press i to toggle the "ignored" status of an issue, and s to save your changes to a .pyspector_baseline.json file. This baseline file will be automatically loaded on subsequent scans.
+
+## Automation and Integration
+
+PySpector includes Shell helper scripts to integrate security scanning directly into your development and operational workflows.
+
+### Git Pre-Commit Hook
+
+To ensure that no new high-severity issues are introduced into the codebase, you can set up a Git pre-commit hook. This hook will automatically scan staged Python files before each commit and block the commit if any HIGH or CRITICAL issues are found.
+
+**To set up the hook, run the following script from the root of your Git repository:**
+```bash
+./scripts/setup_hooks.sh
+```
+This script creates an executable .git/hooks/pre-commit file that performs the check. You can bypass the hook for a specific commit by using the --no-verify flag with your git commit command.
+
+## Scheduled Scans with Cron
+
+For continuous monitoring, you can schedule regular scans of your projects using a cron job. PySpector provides an interactive script to help you generate the correct crontab entry.
+
+**To generate your cron job command, run:**
+```bash
+./scripts/setup_cron.sh
+```
+The script will prompt you for the project path, desired scan frequency (daily, weekly, monthly), and a location to store the JSON reports. It will then output the command to add to your crontab, automating your security scanning and reporting process.
+

src/pyspector/config.py

@@ -1,12 +1,12 @@
 from pathlib import Path
-import toml
-import click
+import toml # type: ignore
+import click # type: ignore
 try:
     # Python 3.9+
     import importlib.resources as pkg_resources
 except ImportError:
     # Fallback for older Python versions
-    import importlib_resources as pkg_resources
+    import importlib_resources as pkg_resources # type: ignore
 
 DEFAULT_CONFIG = {
     "exclude": [
@@ -28,10 +28,15 @@ def load_config(config_path: Path) -> dict:
             click.echo(click.style(f"Warning: Could not parse config file '{config_path}'. Using defaults. Error: {e}", fg="yellow"))
     return DEFAULT_CONFIG
 
-def get_default_rules() -> str:
+def get_default_rules(ai_scan: bool = False) -> str:
     """Loads the built-in TOML rules file from package resources."""
     try:
-        # CORRECTED PATH: Look for the 'rules' sub-package within the main 'pyspector' package.
-        return pkg_resources.files('pyspector.rules').joinpath('built-in-rules.toml').read_text(encoding='utf-8')
+        base_rules = pkg_resources.files('pyspector.rules').joinpath('built-in-rules.toml').read_text(encoding='utf-8')
+        if ai_scan:
+            click.echo("[*] AI scanning enabled. Loading additional AI/LLM rules.")
+            ai_rules = pkg_resources.files('pyspector.rules').joinpath('built-in-rules-ai.toml').read_text(encoding='utf-8')
+            # Combine the two rulesets
+            return base_rules + "\n" + ai_rules
+        return base_rules
     except Exception as e:
         raise FileNotFoundError(f"Could not load built-in-rules.toml from package data! Error: {e}")