CytoScnPy - High-Performance Python Static Analysis

A fast, lightweight static analyzer for Python codebase. It’s built in Rust with Python integration and detection of dead code, security issues, and code quality issue, along with useful quality metrics.

Why CytoScnPy?

• Blazing Fast: Faster in dead code detection.
• Memory Efficient: Uses less memory.
• Comprehensive: Dead code, secrets, security, taint analysis, quality metrics
• Framework Aware: Flask, Django, FastAPI, Pydantic, Azure Functions
• Benchmarked: Continuous benchmarking with 135-item ground truth suite

Installation

Linux / macOS:

# Install
curl -fsSLO https://raw.githubusercontent.com/djinn-soul/CytoScnPy/main/install.sh
bash install.sh

Windows (PowerShell):

# Install
Invoke-WebRequest https://raw.githubusercontent.com/djinn-soul/CytoScnPy/main/install.ps1 -OutFile install.ps1
Unblock-File .\install.ps1
powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\install.ps1

This applies RemoteSigned only to the installer child process and does not override organization-enforced execution policy.

Via Pip:

pip install cytoscnpy

From Source:

git clone https://github.com/djinn-soul/CytoScnPy.git
cd CytoScnPy
pip install maturin
maturin develop -m cytoscnpy/Cargo.toml

MCP Server (for AI Assistants)

CytoScnPy includes an MCP server for AI assistant integration via the standalone CLI binary (install script or cytoscnpy-cli build). The Python package does not run mcp-server.

# Start MCP server (standalone CLI)
cytoscnpy mcp-server

For Claude Desktop, Cursor, or GitHub Copilot configuration, see the MCP Server Documentation.

GitHub Action

Integrate CytoScnPy directly into your GitHub Actions workflow:

- name: Run CytoScnPy Analysis
  uses: djinn-soul/CytoScnPy@v1
  with:
    args: "--secrets --danger --quality"

Action Inputs:

Features

• Dead Code Detection: Unused functions, classes, imports, and variables with cross-module tracking.
  • Cascading Detection: Methods inside unused classes are automatically flagged as unused.
  • Auto-Fix: Remove dead code automatically with --fix (preview by default, use --apply to execute).
• Clone Detection: Find duplicate code with --clones.
• Security Analysis: Taint analysis (SQLi, XSS), secret scanning (API keys, suspicious variables), and dangerous code patterns (eval, exec).
• Code Quality Metrics: Cyclomatic complexity, Halstead metrics, Maintainability Index, and raw metrics (LOC, SLOC).
• Framework Support: Native understanding of Flask, Django, FastAPI, Pydantic, and Azure Functions v2 patterns.
• Smart Heuristics: Handles dataclasses, __all__ exports, visitor patterns, and dynamic attributes intelligently.
• Cross-File Detection: Tracks symbol usage across the entire codebase, including nested packages and complex import chains, to ensure code used in other modules is never incorrectly flagged.

Usage

Command Line

cytoscnpy [PATHS]... [OPTIONS]

Examples:

# Dead code analysis
cytoscnpy .                                     # Analyze current directory
cytoscnpy /path/to/project --json               # JSON output for CI/CD

# Security checks (short flags: -s, -d, -q)
cytoscnpy . --secrets --danger --quality
cytoscnpy . -s -d -q                        # Same with short flags

# Confidence threshold (0-100)
cytoscnpy . --confidence 80

# Path filtering
cytoscnpy . --exclude-folder venv --exclude-folder build
cytoscnpy . --include-folder specific_venv      # Override defaults
cytoscnpy . --include-tests                       # Include tests in all scans/metrics/clones

# Jupyter notebooks
cytoscnpy . --include-ipynb --ipynb-cells

# Clone detection (find duplicate code)
cytoscnpy . --clones --clone-similarity 0.8

# Auto-fix dead code (preview first, then apply)
cytoscnpy . --fix                    # Preview changes (dry-run by default)
cytoscnpy . --fix --apply            # Apply changes
cytoscnpy . --fix -a                 # Apply changes (short flag)

# Generate HTML report (quality auto-enabled; add --secrets --danger for security)
cytoscnpy . --html --secrets --danger

# Pre-commit integration
# See https://djinn-soul.github.io/CytoScnPy/pre-commit/ for setup

Common Options:

[!TIP] View the Full CLI Reference for detailed usage, advanced configuration, and quality gate options.

CI/CD Gate Options:

Metric Subcommands

cytoscnpy raw .                    # Raw Metrics (LOC, SLOC, Comments)
cytoscnpy cc .                     # Cyclomatic Complexity
cytoscnpy hal .                    # Halstead Metrics
cytoscnpy mi .                     # Maintainability Index
cytoscnpy stats . --all            # Full project report (secrets, danger, quality)
cytoscnpy stats . --all -o report.md  # Save report to file
cytoscnpy files .                  # Per-file metrics table
cytoscnpy deps .                   # Dependency analysis
cytoscnpy init                     # Scaffold config in the current project

Dependency analysis reports CytoScnPy-style hygiene categories for missing (CSP-R001), unused production (CSP-R002), transitive (CSP-R003), dev dependency used in production (CSP-R004), and standard-library (CSP-R005) dependencies. Development dependencies are not reported as unused by default; pass cytoscnpy deps --include-dev-unused for stricter checks.

Tip: Add --json for machine-readable output, --exclude-folder <DIR> to skip directories globally, or --ignore <PATTERN> for subcommand-specific glob filtering.

⚙️ Configuration

Create .cytoscnpy.toml (uses [cytoscnpy]) or add to pyproject.toml (uses [tool.cytoscnpy]):

.cytoscnpy.toml example:

[cytoscnpy]
# General Settings
confidence = 60  # Minimum confidence threshold (0-100)
exclude_folders = ["venv", ".tox", "build", "node_modules", ".git"]
include_folders = ["src", "tests"]  # Optional: whitelist folders
include_tests = false
include_ipynb = false

# Analysis Features
secrets = true
danger = true
quality = true

# Fail Threshold (exit code 1 if exceeded)
fail_threshold = 10.0  # Fail if >10% of code is unused
# fail_threshold = 0.0  # Zero tolerance: fail on any unused code
# CLI shortcut: --fail-on-any uses zero tolerance unless fail_threshold is set

# Code Quality Thresholds
max_lines = 100       # Max lines per function
max_args = 5          # Max arguments per function
max_complexity = 10   # Max cyclomatic complexity
max_nesting = 4       # Max indentation depth
min_mi = 65.0         # Minimum Maintainability Index
ignore = ["CSP-P003"] # Ignore specific rule IDs

# Advanced Secret Scanning
[cytoscnpy.secrets_config]
entropy_enabled = true
entropy_threshold = 4.5  # Higher = more random (API keys usually >4.0)
min_length = 16          # Min length to check for entropy
scan_comments = true     # Scan comments for secrets
skip_docstrings = false  # Skip docstrings in entropy scanning
min_score = 50           # Minimum confidence score (0-100)
suspicious_names = ["db_config", "oauth_token"] # Add custom suspicious variable names

# Custom Secret Patterns
[[cytoscnpy.secrets_config.patterns]]
name = "Slack Token"
regex = "xox[baprs]-([0-9a-zA-Z]{10,48})"
severity = "HIGH"

# Danger + Taint Configuration
[cytoscnpy.danger_config]
enable_taint = true
severity_threshold = "LOW" # LOW, MEDIUM, HIGH, CRITICAL
excluded_rules = ["CSP-D101"]
custom_sources = ["mylib.get_input"]
custom_sinks = ["mylib.exec"]

Note: ipynb_cells is currently CLI-only. include_ipynb is supported in config files.

CI/CD Quality Gates

Configure quality gates for CI/CD pipelines. Set thresholds and the CLI exits with code 1 if exceeded.

CLI Flags:

# Unused code percentage gate
cytoscnpy . --fail-threshold 5  # Fail if >5% unused

# Complexity gate
cytoscnpy . --max-complexity 10  # Fail if any function >10

# Maintainability Index gate
cytoscnpy . --min-mi 40  # Fail if MI <40

# Quiet mode for clean CI output
cytoscnpy . --fail-threshold 5 --quiet

Priority: CLI flag > config file > environment variable > default

Environment Variable: CYTOSCNPY_FAIL_THRESHOLD=5.0

Performance

Accuracy (Benchmark Suite: 135 items)

See benchmark/README.md for detailed comparison against Vulture, Flake8, Pylint, Ruff, and others.

Contributing

See CONTRIBUTING.md for development setup, testing instructions, and guidelines.

License

Apache-2.0 License - see License file for details.

Links

• Documentation: CytoScnPy
• PyPI: PyPi
• VS Code Extension: VS Code Marketplace
• Roadmap: docs/roadmap.md

References

CytoScnPy's design and implementation are inspired by:

• Skylos
• Radon

⭐ Star this repo if you find it helpful!

Developed from scratch with assistance from Gemini AI.