License: Apache 2.0 CI/CD Ready codecov PyPI - Python Version PyPI version Downloads/month VS Code Marketplace GitHub stars Astronomer Trust Discord

English | Chinese README

Real-world validation: Skylos-assisted dead-code cleanup PRs have been merged in Black, NetworkX, Optuna, mitmproxy, pypdf, beets, and Flagsmith. These are accepted cleanup PRs, not project endorsements. See Real-World Results.

Star authenticity audit: A local Astronomer scan on April 26, 2026 computed 420 stargazers and returned overall trust: A. StarGuard also reported low fake-star risk.

What Is Skylos?

Skylos is an open-source static analysis tool and CI/CD PR gate for Python, TypeScript, JavaScript, Java, Go, PHP, Rust, and Dart repositories. It combines dead code detection, security scanning, secrets detection, code quality checks, and AI-generated code guardrails in one local-first workflow.

If you use tools like Vulture, Bandit, Semgrep, CodeQL, or GitHub Advanced Security, Skylos is designed to complement that workflow with framework-aware dead code detection, diff-aware regression checks, and PR-native feedback.

Start In 60 Seconds

pip install skylos
skylos .

If Skylos catches something useful in your repo, star it so more maintainers can find it.

Add security, secrets, quality, and dependency checks:

skylos . -a

Create a project config with thresholds, ignores, template hooks, and vibe dictionary extensions:

skylos init

Create a starter local rule pack:

skylos rules init
skylos rules validate .skylos/rules/local.yml
skylos rules list --json
skylos rules list cross --json
skylos rules list --packs --json
skylos cache stats

Generate a GitHub Actions PR gate:

skylos cicd init
git add .github/workflows/skylos.yml
git commit -m "Add Skylos CI gate"
git push

Need more commands? Read the CLI Reference.

Choose Your Workflow

Goal	Command	What You Get	More Detail
First dead-code scan	`skylos .`	Finds unused functions, classes, imports, files, and framework entrypoint mistakes	Dead code docs
Security and quality audit	`skylos . -a`	Adds dangerous flow, secrets, dependency, and quality checks	Security docs
PR gate	`skylos cicd init`	Generates a GitHub Actions workflow with annotations and failure thresholds	CI/CD guide
Readable terminal report	`skylos . --format pretty`	Groups findings by file with severity badges, snippets, and copyable `file:line` locations	CLI output modes
Selectable terminal triage	`skylos . --tui`	Opens a keyboard-driven category list, finding list, and detail pane	CLI output modes
IDE/test-script output	`skylos --format concise src/test.py`	Prints only `file:line` findings and exits non-zero when findings exist	CLI Reference
Changed-lines review	`skylos . -a --diff origin/main`	Keeps findings focused on active work instead of legacy debt	Quality gate docs
Runtime-assisted dead-code check	`skylos . --trace`	Uses runtime traces to reduce dynamic-code false positives	Smart tracing
Local rule pack	`skylos rules init`	Scaffolds YAML rules for project-specific security and quality checks	Custom rules
AI-assisted review	`skylos agent scan .`	Static analysis plus optional LLM review and fix suggestions	AI features
LLM app defense	`skylos defend .`	Finds missing AI app guardrails mapped to OWASP LLM risks	AI defense
Technical debt triage	`skylos debt .`	Ranks hotspots and debt trends	Technical debt

What Skylos Catches

Category	Examples	Why It Matters
Dead code	unused functions, classes, imports, package entrypoints, route handlers	reduces maintenance cost without breaking dynamic frameworks
Security flaws	SQL injection, XSS, SSRF, path traversal, command injection, unsafe deserialization	catches exploitable flows before code reaches main
Secrets	API keys, tokens, private credentials, high-entropy strings	prevents credentials from leaking through commits and PRs
CI/CD workflows	GitHub Actions and GitLab CI dangerous triggers, unpinned actions/includes, broad tokens, OIDC misuse, cache poisoning, mutable images	reduces CI/CD supply-chain risk before release jobs run
Quality regressions	complexity, deep nesting, duplicate branches, long functions, inconsistent returns	keeps AI-assisted refactors from adding brittle code
AI code mistakes	phantom security calls, missing decorators, unfinished stubs, disabled controls, network calls without timeouts	catches common hallucinated or incomplete code paths
LLM app risks	unsafe tool use, prompt injection exposure, missing output validation, missing rate limits	helps teams ship AI features with guardrails

See the full Rules Reference.

Why Teams Use Skylos

Framework-aware dead code detection: understands FastAPI, Django, Flask, pytest, SQLAlchemy, Next.js, React, package entrypoints, and common plugin patterns.
CI/CD-first workflow: run locally, gate PRs, annotate GitHub diffs, and keep legacy findings under control with baselines.
Local-first by default: core static analysis does not require cloud upload or LLM calls.
AI-era regression checks: catches removed validation, auth, logging, CSRF, rate limiting, missing timeouts, and other controls during AI-assisted edits.
Configurable guardrails: extend prompt templates and vibe-code dictionaries from project config without editing Skylos source.
One command surface: dead code, security, secrets, quality, technical debt, agent review, and AI defense live behind one CLI.

Install Options

# Core static analysis
pip install skylos

# LLM-powered agent workflows
pip install "skylos[llm]"

# All published optional extras
pip install "skylos[all]"

Container image:

docker pull ghcr.io/duriantaco/skylos:latest
docker run --rm -v "$PWD":/work -w /work ghcr.io/duriantaco/skylos:latest . --json --no-provenance

See Installation for source installs, container usage, and optional dependencies.

Configure Templates And Vibe Checks

Run skylos init to add these sections to pyproject.toml:

[tool.skylos.templates]
# security = ".skylos/templates/security.md"
# quality = ".skylos/templates/quality.md"
# security_audit = ".skylos/templates/security_audit.md"
# review = ".skylos/templates/review.md"

[tool.skylos.vibe]
extra_phantom_names = ["verify_enterprise_auth"]
extra_phantom_decorators = ["tenant_admin_required"]
extra_credential_names = ["tenant_signing_secret"]
extra_network_timeout_calls = ["vendor_sdk.fetch"]

Template files extend Skylos' built-in prompts; they do not replace the JSON-only output contract or untrusted-code safety rules. Vibe dictionary extensions let teams teach Skylos about local fake-auth helpers, project credential names, sensitive files, and network calls that must set timeouts.

Language Support

Language	Dead Code	Security	Quality	Notes
Python	Yes	Yes	Yes	strongest coverage; framework-aware static analysis and optional tracing
TypeScript / JavaScript	Yes	Yes	Yes	Tree-sitter parsing, package graph reachability, framework conventions
Java	Yes	Yes	Yes	Tree-sitter parsing and structured security-flow analysis
Go	Yes	Partial	Partial	dead-code and selected security benchmark coverage
PHP	Yes	Yes	Partial	PHP parser coverage plus taint-style security sinks and sources
Rust	Yes	Yes	Partial	Rust parser coverage plus security sink/source checks
Dart	Yes	Yes	Partial	Dart parser coverage plus selected security sinks and sources

See Rules Reference for rule families and scanner scope.

Benchmark Snapshot

Skylos has checked-in regression benchmarks for dead code, security, quality, and agent review. These are strict regression gates, not broad proof that any tool is universally state of the art.

Suite	Current Skylos Result	Baseline
Dead code regression	16 cases, TP=36 FP=0 FN=0 TN=59, score 100.0	Ruff score 62.67; Vulture not installed in latest local rerun
Security regression	20 cases, TP=11 FP=0 FN=0 TN=10, score 100.0	Bandit score 47.14 on Python-applicable cases
Quality regression	6 cases, score 100.0	regression gate only
Agent review	25 cases, score 100.0	regression gate only

Frozen golden-v0.2 highlights:

Frozen Suite	Skylos Result	Caveat
Dead code seeded dev	overall score 96.28; TS/JS/Go/Java score 100.0; Python score 93.33	Python residuals are label-review items
Security seeded dev	overall score 96.52; full recall with one Python `urljoin` false positive	label should be reviewed
OWASP Java security dev	TP=105 FP=0 FN=15 TN=120, score 94.37	request-wrapper, LDAP, XPath, and property weak-hash gaps remain
Quality seeded dev	TP=1 FP=0 FN=0 TN=1, score 100.0	one seeded case only

For methodology, commands, competitor rows, and caveats, see BENCHMARK.md.

Integrations

Integration	Link	Purpose
GitHub Action	GitHub Action	PR gates, annotations, and CI enforcement
VS Code extension	VS Code extension	in-editor findings and AI-assisted fixes
MCP server	MCP setup	expose Skylos scans to AI agents and coding assistants
Docker image	Installation	run Skylos without a local Python install
Skylos Cloud	Cloud workflow	optional upload and dashboard workflows

Generate a GitHub Actions workflow from the CLI:

skylos cicd init --upload
skylos cicd init --upload --scan-path apps/api

The generated upload workflow uses GitHub OIDC, sends PR head commit/branch metadata, and supports monorepo subprojects through --scan-path.

Documentation Map

Need	Read This
Install options, source install, and Docker	Installation
First scan and core workflows	Quick Start
CLI commands, flags, and examples	CLI Reference
CLI output modes, pretty reports, and TUI controls	CLI Output Modes
CI setup, PR gates, annotations, and branch protection	CI/CD
Dead-code behavior and framework awareness	Dead Code Detection
Security scanning and taint analysis	Security Analysis
Rule ID prefixes and product terminology	Rule Dictionary
Agent scan, verification, remediation, and model setup	AI Features
AI defense checks and LLM guardrails	AI Defense
MCP server setup	MCP Server
Real-world merged cleanup PRs	Real-World Results
Baselines, filtering, suppressions, and whitelists	Configuration
Smart tracing	Smart Tracing
Rule families and language support	Rules Reference
Cloud uploads and dashboard flow	CLI to Dashboard
VS Code extension	VS Code Extension
Benchmarks and methodology	BENCHMARK.md
Security policy	SECURITY.md
Release process	RELEASE_WORKFLOW.md
Contribution priorities	ROADMAP.md
Contributing	CONTRIBUTING.md

Common Questions

Does Skylos replace Bandit, Semgrep, CodeQL, or Vulture?

No. Skylos can run alongside them. It focuses on framework-aware dead-code signal, PR gating, AI-era regression checks, and a combined workflow across dead code, security, secrets, and quality.

Does Skylos require an LLM?

No. Core static analysis runs locally without API keys. LLM features are optional through skylos[llm] and agent commands.

Can I use it only on changed code?

Yes. Use skylos . -a --diff origin/main locally or configure CI gates to focus on new findings.

How should I handle intentional dynamic code?

Use baselines, whitelists, inline suppressions, or runtime tracing. See the configuration docs and smart tracing docs.

Contributing And Support

Report security issues through SECURITY.md.
Open bugs and false-positive reports with minimal repros.
Check ROADMAP.md for useful contribution areas.
Read CONTRIBUTING.md before sending a pull request.
See QUALITY.md for project quality and gate expectations.
Join the Discord for community support.

License

Skylos is licensed under the Apache License 2.0.

mcp-skylos