What: Local-first scanner and PR gate for dead code, security, secrets, quality, and AI-generated-code mistakes across Python, TS/JS, Java, Go, PHP, and Rust.
Install: pip install skylos
Use: skylos . for dead code, skylos . -a for the main security/secrets/quality audit, skylos cicd init for CI.
Main commands: skylos init, skylos rules init, skylos defend ., skylos agent scan ., skylos debt ..
Website | Docs | Quick Start | GitHub Action | VS Code Extension | Real-World Results | Benchmarks | Contributing
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.
Skylos is an open-source static analysis tool and CI/CD PR gate for Python, TypeScript, JavaScript, Java, Go, PHP, and Rust 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.
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 . -aCreate a project config with thresholds, ignores, template hooks, and vibe dictionary extensions:
skylos initCreate a starter local rule pack:
skylos rules init
skylos rules validate .skylos/rules/local.ymlGenerate a GitHub Actions PR gate:
skylos cicd init
git add .github/workflows/skylos.yml
git commit -m "Add Skylos CI gate"
git pushNeed more commands? Read the CLI Reference.
| 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 |
| 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 |
| 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 |
| 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.
- 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.
# 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-provenanceSee Installation for source installs, container usage, and optional dependencies.
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 | 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 |
See Rules Reference for rule families and scanner scope.
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.
| 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/apiThe generated upload workflow uses GitHub OIDC, sends PR head commit/branch
metadata, and supports monorepo subprojects through --scan-path.
| Need | Read This |
|---|---|
| Install options, source install, and Docker | Installation |
| First scan and core workflows | Quick Start |
| CLI commands, flags, and examples | CLI Reference |
| 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 |
| 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 |
| Contributing | CONTRIBUTING.md |
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.
- Report security issues through SECURITY.md.
- Open bugs and false-positive reports with minimal repros.
- Read CONTRIBUTING.md before sending a pull request.
- See QUALITY.md for project quality and gate expectations.
- Join the Discord for community support.
Skylos is licensed under the Apache License 2.0.