Skylos: Open-Source Python SAST, Dead Code Detection, and AI Code Security

Find unused code, hardcoded secrets, exploitable flows, and AI-generated security regressions in Python, TypeScript, and Go. Run locally or gate pull requests in CI/CD.

📖 Website · Documentation · Blog · GitHub Action · VS Code Extension · MCP Server

English | 中文

Skylos is an open-source static analysis tool and PR gate for Python, TypeScript, and Go. It helps teams detect dead code, hardcoded secrets, exploitable flows, and AI-generated security regressions before they land in main.

If you use Vulture for dead code, Bandit for security checks, or Semgrep/CodeQL for CI enforcement, Skylos combines those workflows with framework-aware dead code detection and diff-aware regression detection for AI-assisted refactors.

The core use case is straightforward: run it locally, add it to CI, and gate pull requests on real findings with GitHub annotations and review comments. Advanced features like AI defense, remediation agents, VS Code, MCP, and cloud upload are available, but you do not need any of them to get value from Skylos.

• Python teams that want dead code detection with fewer false positives than Vulture
• Repositories using Cursor, Copilot, Claude Code, or other AI coding assistants
• CI/CD pull request gates with GitHub annotations and review comments
• Python LLM applications that need OWASP LLM Top 10 checks

• CLI for local scans and CI/CD workflows
• GitHub Action for pull request gating and annotations
• VS Code extension for in-editor findings and AI-assisted fixes
• MCP server for AI agents and coding assistants

1. Better dead code signal on real frameworks: Skylos understands FastAPI, Django, Flask, pytest, Next.js, React, and more, so dynamic code produces less noise.
2. Diff-aware AI regression detection: Skylos can catch removed auth decorators, CSRF, rate limiting, validation, logging, and other controls that disappear during AI-assisted refactors.
3. One workflow instead of three tools: Dead code, security scanning, and PR gating live in the same CLI and CI flow.
4. Local-first by default: You can keep scans on your machine and add optional AI or cloud features later if you need them.
5. Self-explaining output: Every table prints a legend explaining what each column and number means — no manual required.

Benchmarked on 9 popular Python repos (350k+ combined stars) + TypeScript (consola). Every finding manually verified. Full case study →

# Generate a GitHub Actions workflow in 30 seconds
skylos cicd init

# Commit and push to activate
git add .github/workflows/skylos.yml && git push

What you get:

• Automatic dead code detection on every PR
• Security vulnerability scanning (SQLi, secrets, dangerous patterns)
• Quality gate that fails builds on critical issues
• Inline PR review comments with file:line links
• GitHub Annotations visible in the "Files Changed" tab

No configuration needed - works out of the box with sensible defaults. See CI/CD section for customization.

• What is Skylos?
• Quick Start
• Technical Debt Hotspots
• Key Capabilities
• Installation
• Skylos vs Vulture
• Projects Using Skylos
• How It Works
• Advanced Workflows
• CI/CD
• MCP Server
• Baseline Tracking
• Gating
• VS Code Extension
• Integration and Ecosystem
• Auditing and Precision
• Coverage Integration
• Filtering
• Release Automation
• Release Workflow Runbook
• CLI Options
• FAQ
• Limitations and Troubleshooting
• Contributing
• Roadmap
• License
• Contact

If you are evaluating Skylos, start with the core workflow below. The LLM and AI defense commands are optional.

Use skylos debt <path> to rank structural debt hotspots without collapsing everything into a single urgency number.

• score is the project-level structural debt score.
• priority is the hotspot triage score used for ordering fix candidates.
• --changed limits the visible hotspot list to changed files, but keeps the structural debt score anchored to the whole project.

# Full project debt scan
skylos debt .

# Review only changed hotspots without distorting the project score
skylos debt . --changed

# Compare the current project against a saved debt baseline
skylos debt . --baseline

# Save a repo-level debt baseline
skylos debt . --save-baseline

Debt policy files such as skylos-debt.yaml are discovered from the scan target upward, and explicit CLI flags like --top override policy defaults.

Backup (GitHub): #82

The core product is dead code detection, security scanning, and PR gating. The AI-focused features below are optional layers on top of that baseline workflow.

• Taint Analysis: Traces untrusted input from API endpoints to databases to prevent SQL Injection and XSS.
• Secrets Detection: Hunts down hardcoded API keys (AWS, Stripe, OpenAI) and private credentials before commit.
• Vulnerability Checks: Flags dangerous patterns like eval(), unsafe pickle, and weak cryptography.

Skylos can also flag common AI-generated code mistakes. Every finding includes vibe_category and ai_likelihood (high/medium/low) metadata so you can filter them separately if you want.

• Phantom Call Detection: Catches calls to security functions (sanitize_input, validate_token, check_permission, etc.) that are never defined or imported — AI hallucinates these constantly. hallucinated_reference, high
• Phantom Decorator Detection: Catches security decorators (@require_auth, @rate_limit, @authenticate, etc.) that are never defined or imported. hallucinated_reference, high
• Unfinished Generation: Detects functions with only pass, ..., or raise NotImplementedError — AI-generated stubs that silently do nothing in production. incomplete_generation, medium
• Undefined Config: Flags os.getenv("ENABLE_X") referencing feature flags that are never defined anywhere in the project. ghost_config, medium
• Stale Mock Detection: Catches mock.patch("app.email.send_email") where send_email no longer exists — AI renames functions but leaves tests pointing at the old name. stale_reference, medium
• Security TODO Scanners: Flags # TODO: add auth placeholders that AI left behind and nobody finished.
• Disabled Security Controls: Detects verify=False, @csrf_exempt, DEBUG=True, and ALLOWED_HOSTS=["*"].
• Credential & Randomness Checks: Catches hardcoded passwords and random.choice() used for security-sensitive values like tokens and OTPs.

These checks run under --danger and look for prompt injection patterns or obfuscated instructions in repository content.

• Multi-File Prompt Injection Scanner: Scans Python, Markdown, YAML, JSON, TOML, and .env files for hidden instruction payloads — instruction overrides ("ignore previous instructions"), role hijacking ("you are now"), AI-targeted suppression ("do not flag", "skip security"), data exfiltration prompts, and AI-targeting phrases.
• Text Canonicalization Engine: NFKC normalization, whitespace folding, and confusable replacement neutralize obfuscation before pattern matching.
• Zero-Width & Invisible Unicode: Detects zero-width spaces, joiners, BOM, and bidi overrides (U+200B–U+202E) that hide payloads from human reviewers.
• Base64 Obfuscation Detection: Automatically decodes base64-encoded strings and re-scans for injection content.
• Homoglyph / Mixed-Script Detection: Flags Cyrillic and Greek characters mixed with Latin text (e.g., Cyrillic 'а' in password) that bypass visual review.
• Location-Aware Severity: Findings in README files, HTML comments, and YAML prompt fields get elevated severity. Test files are automatically skipped.

Static analysis for AI application security that maps every LLM call in your Python codebase and checks for missing guardrails. Python only (TypeScript/Go support planned).

# Discover all LLM integrations
skylos discover .

# Check defenses and get a scored report
skylos defend .

# CI gate: fail on critical gaps, require 70% defense score
skylos defend . --fail-on critical --min-score 70

# JSON output for dashboards and pipelines
skylos defend . --json -o defense-report.json

# Filter by OWASP LLM Top 10 category
skylos defend . --owasp LLM01,LLM04

13 checks across defense and ops:

Defense and ops scores are tracked separately — adding logging won't inflate your security score.

Custom policy via skylos-defend.yaml:

rules:
  model-pinned:
    severity: critical    # Upgrade severity
  input-length-limit:
    enabled: false        # Disable check
gate:
  min_score: 70
  fail_on: high

Supports OpenAI, Anthropic, Google Gemini, Cohere, Mistral, Ollama, Together AI, Groq, Fireworks, Replicate, LiteLLM, LangChain, LlamaIndex, CrewAI, and AutoGen.

• Find Unused Code: Identifies unreachable functions, orphan classes, and unused imports with confidence scoring.
• Smart Tracing: Distinguishes between truly dead code and dynamic frameworks (Flask/Django routes, Pytest fixtures).
• Safe Pruning: Uses LibCST to safely remove dead code without breaking syntax.

• Context-aware audits: Combines static analysis speed with LLM reasoning to validate findings and filter noise.
• Remediation workflow: skylos agent remediate can scan, generate fixes, run tests, and optionally open a PR.
• Local model support: Supports Ollama and other OpenAI-compatible local endpoints if you want code to stay on your machine.

• 30-Second Workflow Setup: skylos cicd init generates GitHub Actions workflows with sensible defaults.
• Diff-Aware Enforcement: Gate only the lines that changed, fail on severity thresholds, and keep legacy debt manageable with baselines.
• PR-Native Feedback: GitHub annotations, inline review comments, and optional dashboard upload keep findings where teams already work.
• Corpus Guard: Require the Corpus Guard workflow on PRs to catch dead-code precision regressions against curated framework and language fixtures.

• CST-safe removals: Uses LibCST to remove selected imports or functions (handles multiline imports, aliases, decorators, async etc..)
• Logic Awareness: Deep integration for Python frameworks (Django, Flask, FastAPI) and TypeScript (Tree-sitter) to identify active routes and dependencies.
• Granular Filtering: Skip lines tagged with # pragma: no skylos, # pragma: no cover, or # noqa

• Coverage Integration: Auto-detects .skylos-trace files to verify dead code with runtime data
• Quality Gates: Enforces hard thresholds for complexity, nesting, and security risk via pyproject.toml to block non-compliant PRs
• Interactive CLI: Manually verify and remove/comment-out findings through an inquirer-based terminal interface
• Security-Audit Mode: Leverages an independent reasoning loop to identify security vulnerabilities

• Unused Fixture Detection: Finds unused @pytest.fixture definitions in test_*.py and conftest.py
• Cross-file Resolution: Tracks fixtures used across modules, not just within the same file

Languages are auto-detected by file extension. Mixed-language repos work out of the box. No Node.js or JDK required — all parsers are built-in via Tree-sitter.

Framework-aware: Next.js convention exports (page.tsx, layout.tsx, route.ts, middleware.ts), config exports (getServerSideProps, generateMetadata, revalidate), React patterns (memo, forwardRef), and exported custom hooks (use*) are automatically excluded from dead code reports.

TypeScript dead code detection tracks: callbacks, type annotations, generics, decorators, inheritance (extends), object shorthand, spread, re-exports, and typeof references. Benchmarked at 95% recall with 0 false positives on alive code.

## from pypi
pip install skylos

## with LLM-powered features (agent verify, agent remediate, etc.)
pip install skylos[llm]

## with Rust-accelerated analysis (up to 63x faster)
pip install skylos[fast]

## both
pip install skylos[llm,fast]

## or from source
git clone https://github.com/duriantaco/skylos.git
cd skylos

pip install .

skylos[fast] installs an optional Rust backend that accelerates clone detection (63x), file discovery (5x), coupling analysis, and cycle detection. Same results, just faster. Pure Python works fine without it — the Rust module is auto-detected at runtime.

skylos[llm] installs litellm for LLM-powered features (skylos agent verify, skylos agent remediate, --llm). Core static analysis works without it.

After installation, we recommend:

1. Set up CI/CD (30 seconds):

   skylos cicd init
   git add .github/workflows/skylos.yml && git push

   This will automatically scan every PR for dead code and security issues.

2. Run your first scan:

   skylos .                              # Dead code only
   skylos . --danger --secrets           # Include security checks

3. Keep scans focused on active work:

   skylos . --diff origin/main

4. Try advanced workflows only if you need them:

   skylos agent review . --model gpt-4.1
   skylos defend .

See all commands in the Quick Start table

We benchmarked Skylos against Vulture on 9 of the most popular Python repositories on GitHub — 350k+ combined stars, covering HTTP clients, web frameworks, CLI tools, data validation, terminal UIs, and progress bars. Every single finding was manually verified against the source code. No automated labelling, no cherry-picking.

We deliberately chose projects that stress-test dead code detection in different ways:

No repo was excluded for having unfavorable results. We include repos where Vulture beats Skylos (click, starlette, tqdm).

Skylos finds 7 more dead items than Vulture with 3x fewer false positives.

Vulture uses flat name matching — if the bare name X appears anywhere as a string or identifier, all definitions named X are considered used. This works well for simple cases but drowns in noise on framework-heavy codebases:

• Flask (260 Vulture FP): Vulture flags every Jinja2 template global, Werkzeug protocol method, and Flask extension hook. Skylos recognizes Flask/Werkzeug patterns.
• Pydantic (112 Vulture FP): Vulture flags all config class annotations, TYPE_CHECKING imports, and mypy plugin hooks. Skylos understands Pydantic model fields and __getattr__ dynamic access.
• FastAPI (102 Vulture FP): Vulture flags 100+ OpenAPI spec model fields (Pydantic BaseModel attributes like maxLength, exclusiveMinimum). Skylos recognizes these as schema definitions.
• httpx (59 Vulture FP): Vulture flags every transport and auth protocol method. Skylos suppresses interface implementations.

• click (8 vs 6 FP): IO protocol methods (readable, readinto) on io.RawIOBase subclasses — called by Python's IO stack, not by direct call sites.
• starlette (4 vs 2 FP): Instance method calls across files (obj.method()) not resolved back to class definitions.
• tqdm (18 vs 37 FP, 0 vs 1 TP): Skylos misses 1 dead function in __init__.py because it suppresses __init__.py definitions as potential re-exports.

Reproduce any benchmark: cd real_life_examples/{repo} && python3 ../benchmark_{repo}.py

Full methodology and per-repo breakdowns in the skylos-demo repository.

We also benchmarked Skylos against Knip on a real-world TypeScript library:

Both tools find all dead code. Skylos has ~5x better precision — Knip incorrectly flags package entry points as dead files (its package.json exports point to dist/ not src/) and reports public API re-exports as unused.

Reproduce: cd real_life_examples/consola && python3 ../benchmark_consola.py

If you use Skylos in a public repository, open an issue and add it here. This list is based on self-submissions, so it will stay small until more teams opt in publicly.

Skylos Uses Skylos on itself for dead code, security, and CI gating Your project here Add yours

Add your project →

Skylos builds a reference graph of your entire codebase - who defines what, who calls what, across all files.

Parse all files -> Build definition map -> Track references -> Find orphans (zero refs = dead)

Static analysis often struggles with Python's dynamic nature (e.g., getattr, pytest.fixture). Skylos minimizes false positives through:

1. Confidence Scoring: Grades findings (High/Medium/Low) so you only see what matters.
2. Hybrid Verification: Uses LLM reasoning to double-check static findings before reporting.
3. Runtime Tracing: Optional --trace mode validates "dead" code against actual runtime execution.

skylos . -c 60  # Default: high-confidence findings only
skylos . -c 30  # Include framework helpers  
skylos . -c 0  # Everything

When Skylos sees Flask, Django, FastAPI, Next.js, or React imports, it adjusts scoring automatically:

Tests call code in weird ways that look like dead code. By default, Skylos excludes:

# These are auto-excluded (confidence set to 0)
/project/tests/test_user.py
/project/test/helper.py  

# These are analyzed normally
/project/user.py
/project/test_data.py  # Doesn't end with _test.py

Want test files included? Use --include-folder tests.

When ambiguous, we'd rather miss dead code than flag live code as dead.

Framework endpoints are called externally (HTTP, signals). Name resolution handles aliases. When things get unclear, we err on the side of caution.