PISCES

AI-Assisted · Self-Healing · Human-Governed Python Security Remediation Patcher

Overview

Pisces is a Python security CLI that detects common vulnerabilities, explains findings with an LLM, proposes minimal patches, validates them with your test suite, and rolls them back when validation fails. Source changes remain human-approved by default.

Key Features

• AST-first and regex-fallback security scanning.
• Seven built-in rules for secrets, command injection, unsafe subprocesses, unsafe deserialization, disabled TLS verification, code injection, and dangerous filesystem operations.
• Excludes .venv, __pycache__, and other irrelevant directories.
• LLM explanations with source snippets and AST context.
• Human-in-the-loop patch approval.
• Atomic patching, checkpoints, rollback, and self-healing retries.
• Local repair history and a debounced watch mode.
• OpenAI, Anthropic, Gemini, Groq, Ollama, and LM Studio support.

⚙️ How it Works

⚙️ The Repair State Machine

Installation

Pisces requires Python 3.10 or newer.

pip install pisces-cli

Quick Usage

pisces init
pisces config
pisces scan .
pisces explain path/to/file.py:42
pisces fix path/to/file.py:42
pisces history

Set the API key for the provider configured in pisces.toml, for example:

export GROQ_API_KEY="your-key"

On Windows PowerShell:

$env:GROQ_API_KEY = "your-key"

Ollama and LM Studio use local endpoints and do not require an API key.

Configuration

Run pisces init to create a project configuration:

[llm]
provider = "groq"
model = "llama-3.3-70b-versatile"

[repair]
max_attempts = 3
require_approval = true

[validation]
test_command = "pytest"

[scan]
exclude = [
    ".git",
    ".venv",
    "venv",
    "__pycache__",
    "node_modules",
    ".pisces",
    "dist",
    "build",
]

Do not put API keys in this file. Use environment variables instead.

CLI Reference

pisces fix also supports --dry-run, --no-judge, and --max-attempts N. pisces scan returns exit code 1 when findings meet the selected severity threshold.

Built-in Security Rules

Architecture and Workflow

The workflow covers project initialization, deterministic security scanning, LLM-powered explanations and patch generation, human approval, checkpointing, test validation, rollback, and self-healing retries.

The deterministic scanner does not call an LLM. LLMs are used for explanations, patch generation, and optional patch judging. Source changes require human approval by default.

The deterministic scanner does not call an LLM. LLMs are used for explanations, patch generation, and optional patch judging.

Links

• GitHub: https://github.com/richochetclementine1315/pisces
• Issues: https://github.com/richochetclementine1315/pisces/issues
• PyPI: https://pypi.org/project/pisces-cli/

License

MIT © Mrinmoy Matilal