Metadata-Version: 2.4
Name: skylos
Version: 4.15.0
Summary: Open-source AI code security and static analysis for Python, TypeScript/JavaScript, Go, Java, PHP, Rust, and Dart. Finds dead code, secrets, vulnerabilities, and diff-aware regressions.
Author-email: Aaron Oh <aaronoh2015@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://skylos.dev
Project-URL: Documentation, https://docs.skylos.dev
Project-URL: Repository, https://github.com/duriantaco/skylos
Project-URL: Changelog, https://github.com/duriantaco/skylos/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/duriantaco/skylos/issues
Project-URL: Discord, https://discord.gg/Ftn9t9tErf
Project-URL: MCP Server, https://github.com/duriantaco/skylos/tree/main/skylos_mcp
Keywords: static-analysis,dead-code,unused-code,unused-imports,security,linter,code-quality,sast,python-sast,vulnerability-scanner,python-linter,python-security,python-security-scanner,typescript-linter,quality-gate,ci-cd,github-actions,github-actions-security,gitlab-ci,gitlab-ci-security,supply-chain-security,code-review,secrets-detection,mcp,mcp-server,ai-agent,ai-tool,coding-agent,vulture-alternative,bandit-alternative,semgrep-alternative,code-scanner,dead-code-detector,devsecops,vibe-coding,ai-generated-code,ai-code-security,prompt-injection,ai-supply-chain-security,phantom-function,hallucinated-dependency,copilot-review
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: inquirer>=3.0.3
Requires-Dist: libcst>=1.8.2
Requires-Dist: rich>=14.0.0
Requires-Dist: textual>=1.0.0
Requires-Dist: keyring!=3.4.2,>=25.6.0
Requires-Dist: requests
Requires-Dist: tree-sitter>=0.25.2
Requires-Dist: tree-sitter-typescript>=0.23.2
Requires-Dist: tree-sitter-go>=0.23.0
Requires-Dist: tree-sitter-java>=0.23.0
Requires-Dist: tree-sitter-php>=0.24.1
Requires-Dist: tree-sitter-rust>=0.24.2
Requires-Dist: tree-sitter-dart-orchard>=0.3.2
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Requires-Dist: pyyaml
Requires-Dist: networkx
Requires-Dist: pyperclip
Requires-Dist: ca9>=0.1.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: web
Requires-Dist: flask>=2.1.1; extra == "web"
Requires-Dist: flask-cors>=3.0.3; extra == "web"
Provides-Extra: llm
Requires-Dist: litellm<1.84.0,>=1.81.3; extra == "llm"
Provides-Extra: test
Requires-Dist: pytest>=9.0.2; extra == "test"
Provides-Extra: all
Requires-Dist: flask>=2.1.1; extra == "all"
Requires-Dist: flask-cors>=3.0.3; extra == "all"
Requires-Dist: pytest>=9.0.2; extra == "all"
Requires-Dist: litellm<1.84.0,>=1.81.3; extra == "all"
Dynamic: license-file

<div align="center">
    <img src="assets/DOG_1.png" alt="Skylos" width="260">
    <h1>Skylos</h1>
    <h3>Local-first code scanning for dead code, security, secrets, quality, and AI-generated-code mistakes.</h3>
</div>

![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)
![CI/CD Ready](https://img.shields.io/badge/CI%2FCD-30s%20Setup-brightgreen?style=flat&logo=github-actions&logoColor=white)
[![codecov](https://codecov.io/gh/duriantaco/skylos/branch/main/graph/badge.svg)](https://codecov.io/gh/duriantaco/skylos)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/skylos)
[![PyPI version](https://img.shields.io/pypi/v/skylos)](https://pypi.org/project/skylos/)
[![Downloads/month](https://img.shields.io/pypi/dm/skylos)](https://pypistats.org/packages/skylos)
![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/oha.skylos-vscode-extension)
[![GitHub stars](https://img.shields.io/github/stars/duriantaco/skylos)](https://github.com/duriantaco/skylos/stargazers)
[![Astronomer Trust](https://img.shields.io/badge/Astronomer%20Trust-A-brightgreen?style=flat&logo=github&logoColor=white)](#star-authenticity-audit)
[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white)](https://discord.gg/Ftn9t9tErf)

[Website](https://skylos.dev) |
[Docs](https://docs.skylos.dev) |
[Quick Start](https://docs.skylos.dev/quick-start) |
[GitHub Action](./action.yml) |
[VS Code Extension](./editors/vscode/README.md) |
[Real-World Results](./REAL_WORLD_RESULTS.md) |
[Benchmarks](./BENCHMARK.md) |
[Roadmap](./ROADMAP.md) |
[Contributing](./CONTRIBUTING.md)

**English** | [Chinese README](./README_CN.md)

> **Real-world validation:** Skylos-assisted dead-code cleanup PRs have been
> merged in [Black](https://github.com/psf/black/pull/5041),
> [NetworkX](https://github.com/networkx/networkx/pull/8572),
> [Optuna](https://github.com/optuna/optuna/pull/6547),
> [mitmproxy](https://github.com/mitmproxy/mitmproxy/pull/8136),
> [pypdf](https://github.com/py-pdf/pypdf/pull/3685),
> [beets](https://github.com/beetbox/beets/pull/6473), and
> [Flagsmith](https://github.com/Flagsmith/flagsmith/pull/6953).
> These are accepted cleanup PRs, not project endorsements. See
> [Real-World Results](./REAL_WORLD_RESULTS.md).

<a id="star-authenticity-audit"></a>

> **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, 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.

## Start In 60 Seconds

```bash
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:

```bash
skylos . -a
```

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

```bash
skylos init
```

Create a starter local rule pack:

```bash
skylos rules init
skylos rules validate .skylos/rules/local.yml
```

Generate a GitHub Actions PR gate:

```bash
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](https://docs.skylos.dev/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](https://docs.skylos.dev/dead-code-detection) |
| Security and quality audit | `skylos . -a` | Adds dangerous flow, secrets, dependency, and quality checks | [Security docs](https://docs.skylos.dev/security-analysis) |
| PR gate | `skylos cicd init` | Generates a GitHub Actions workflow with annotations and failure thresholds | [CI/CD guide](https://docs.skylos.dev/ci-cd) |
| IDE/test-script output | `skylos --format concise src/test.py` | Prints only `file:line` findings and exits non-zero when findings exist | [CLI Reference](https://docs.skylos.dev/cli-reference) |
| Changed-lines review | `skylos . -a --diff origin/main` | Keeps findings focused on active work instead of legacy debt | [Quality gate docs](https://docs.skylos.dev/quality-gate) |
| Runtime-assisted dead-code check | `skylos . --trace` | Uses runtime traces to reduce dynamic-code false positives | [Smart tracing](https://docs.skylos.dev/smart-tracing) |
| Local rule pack | `skylos rules init` | Scaffolds YAML rules for project-specific security and quality checks | [Custom rules](https://docs.skylos.dev/custom-rules) |
| AI-assisted review | `skylos agent scan .` | Static analysis plus optional LLM review and fix suggestions | [AI features](https://docs.skylos.dev/ai-features) |
| LLM app defense | `skylos defend .` | Finds missing AI app guardrails mapped to OWASP LLM risks | [AI defense](https://docs.skylos.dev/ai-defense) |
| Technical debt triage | `skylos debt .` | Ranks hotspots and debt trends | [Technical debt](https://docs.skylos.dev/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](https://docs.skylos.dev/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

```bash
# Core static analysis
pip install skylos

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

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

Container image:

```bash
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](https://docs.skylos.dev/installation) for source installs,
container usage, and optional dependencies.

## Configure Templates And Vibe Checks

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

```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 |

See [Rules Reference](https://docs.skylos.dev/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](./BENCHMARK.md).

## Integrations

| Integration | Link | Purpose |
|:---|:---|:---|
| GitHub Action | [GitHub Action](./action.yml) | PR gates, annotations, and CI enforcement |
| VS Code extension | [VS Code extension](./editors/vscode/README.md) | in-editor findings and AI-assisted fixes |
| MCP server | [MCP setup](https://docs.skylos.dev/mcp-server) | expose Skylos scans to AI agents and coding assistants |
| Docker image | [Installation](https://docs.skylos.dev/installation) | run Skylos without a local Python install |
| Skylos Cloud | [Cloud workflow](https://docs.skylos.dev/cloud-workflow) | optional upload and dashboard workflows |

Generate a GitHub Actions workflow from the CLI:

```bash
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](https://docs.skylos.dev/installation) |
| First scan and core workflows | [Quick Start](https://docs.skylos.dev/quick-start) |
| CLI commands, flags, and examples | [CLI Reference](https://docs.skylos.dev/cli-reference) |
| CI setup, PR gates, annotations, and branch protection | [CI/CD](https://docs.skylos.dev/ci-cd) |
| Dead-code behavior and framework awareness | [Dead Code Detection](https://docs.skylos.dev/dead-code-detection) |
| Security scanning and taint analysis | [Security Analysis](https://docs.skylos.dev/security-analysis) |
| Agent scan, verification, remediation, and model setup | [AI Features](https://docs.skylos.dev/ai-features) |
| AI defense checks and LLM guardrails | [AI Defense](https://docs.skylos.dev/ai-defense) |
| MCP server setup | [MCP Server](https://docs.skylos.dev/mcp-server) |
| Real-world merged cleanup PRs | [Real-World Results](./REAL_WORLD_RESULTS.md) |
| Baselines, filtering, suppressions, and whitelists | [Configuration](https://docs.skylos.dev/configuration) |
| Smart tracing | [Smart Tracing](https://docs.skylos.dev/smart-tracing) |
| Rule families and language support | [Rules Reference](https://docs.skylos.dev/rules-reference) |
| Cloud uploads and dashboard flow | [CLI to Dashboard](https://docs.skylos.dev/cloud-workflow) |
| VS Code extension | [VS Code Extension](https://docs.skylos.dev/vscode) |
| Benchmarks and methodology | [BENCHMARK.md](./BENCHMARK.md) |
| Security policy | [SECURITY.md](./SECURITY.md) |
| Release process | [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) |
| Contribution priorities | [ROADMAP.md](./ROADMAP.md) |
| Contributing | [CONTRIBUTING.md](./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](https://docs.skylos.dev/configuration) and
[smart tracing docs](https://docs.skylos.dev/smart-tracing).

## Contributing And Support

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

## License

Skylos is licensed under the [Apache License 2.0](./LICENSE).

<!-- mcp-name: io.github.duriantaco/skylos -->
