Skip to main content

FAQ

General​

What is Skylos?​

Skylos is a static analysis tool for Python, TypeScript, JavaScript, Java, Go, PHP, and Rust that detects:

  • Dead code: Unused functions, imports, classes, variables
  • Security vulnerabilities: SQL injection, command injection, SSRF, XSS
  • Code quality issues: High complexity, deep nesting, mutable defaults

Unlike simple linters, Skylos uses taint analysis to trace data flow and framework awareness to reduce false positives.

Is Skylos free?​

Yes. Skylos is open source and free to use. Core static analysis runs locally without an API key. Optional agent workflows can use your own OpenAI, Anthropic, or local OpenAI-compatible model endpoint.

What Python versions are supported?​

Python 3.10 and newer are supported.

Does Skylos work with my framework?​

Skylos has built-in awareness for Django, Flask, FastAPI, Pydantic, pytest, SQLAlchemy, Next.js, React, package entrypoints, and common plugin patterns. Other frameworks work but may need baselines, whitelists, or tracing for implicitly-called code.

How is Skylos different from Pylint/Bandit?​

ToolFocusApproach
PylintStyle + errorsPattern matching
BanditSecurityPattern matching
SkylosDead code + Security + QualityTaint analysis + Framework awareness

Skylos catches vulnerabilities that pattern matchers miss (indirect data flows) and has fewer false positives for dead code (framework awareness).

Installation & Setup​

How do I install Skylos?​

pip install skylos

Verify with skylos --version.

Do I need to configure anything?​

No. Skylos works out of the box with sensible defaults. For customization, run skylos init to create a [tool.skylos] section in your pyproject.toml.

How do I set up AI features?​

Install the LLM extra, set an environment variable, and run an agent command:

pip install "skylos[llm]"
export OPENAI_API_KEY="sk-..."
skylos agent scan .

Usage​

What's the basic command?​

skylos .                              # Dead code only
skylos . -a                           # Main local audit
skylos . --danger --quality --gate    # With quality gate

How do I scan a single file?​

skylos path/to/file.py

How do I exclude folders?​

skylos . --exclude-folder tests --exclude-folder migrations

Or in pyproject.toml:

[tool.skylos]
exclude = ["tests", "migrations"]

How do I ignore specific rules?​

Inline suppression:

def function():  # noqa: skylos
    pass

Global suppression in pyproject.toml:

[tool.skylos]
ignore = ["SKY-D201", "SKY-L002"]

How do I get JSON output?​

skylos . --json -o report.json

What does --confidence do?​

Filters findings by certainty. Default is 60. Use --confidence 80 for fewer, safer results or --confidence 40 to include more uncertain findings.

What do the numbers in the quality table mean?​

Each quality finding has a measured value and a threshold (the configured maximum). For example:

  • Complexity: 14 (max 10) — the function has 14 branches but the limit is 10
  • Deep nesting: depth 6 — the code is 6 levels deep
  • repeated 5× (max 3) — a string literal appears 5 times; extract it to a named constant

You can tune thresholds in pyproject.toml under [tool.skylos].

What does the Conf column mean in dead code results?​

Conf is the confidence score (0–100%). It tells you how certain Skylos is that the code is truly unused:

  • 90–100%: Safe to delete
  • 60–89%: Review first — might be called dynamically
  • Below 60%: Likely a false positive

What do the columns in the security table mean?​

  • Issue — the vulnerability type (e.g. SQL injection) with its rule ID
  • Severity — risk level: Critical > High > Medium > Low
  • Symbol — the function containing the vulnerable code
  • Message — what was found and why it's dangerous

False Positives​

Why is my Flask/Django route flagged as unused?​

Skylos should detect framework decorators. If it doesn't, ensure the file imports the framework, check for non-standard decorator patterns, or add # noqa: skylos. Report undetected patterns on GitHub.

Why is dynamically-called code flagged?​

Static analysis can't see runtime behavior like getattr() calls. Use --trace to capture runtime calls, add # noqa: skylos, or lower the confidence threshold.

Why are my test fixtures flagged?​

Skylos should recognize pytest fixtures. Ensure the file matches test patterns (test_*.py) and has the @pytest.fixture decorator. Report issues with a minimal example.

How do I report a false positive?​

Open an issue at github.com/duriantaco/skylos with a minimal code example, Skylos output, expected behavior, and version.

Security Scanning​

What vulnerabilities does Skylos detect?​

SQL injection, command injection, SSRF, XSS, path traversal, dangerous functions (eval, exec, pickle), weak cryptography, disabled SSL verification, and hardcoded secrets. See Rules Reference for details.

What is taint analysis?​

Taint analysis tracks how untrusted data flows through your code. If tainted data reaches a dangerous function, it's flagged:

user_id = request.args.get("id")                      # Source: tainted
query = f"SELECT * FROM users WHERE id = {user_id}"   # Propagation
cursor.execute(query)                                  # Sink: flagged

How do I fix a SQL injection finding?​

Use parameterized queries:

# Vulnerable
cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")

# Safe
cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))

Why is my code flagged but I sanitize the input?​

Skylos may not recognize custom sanitization functions. Use standard library sanitization, add inline suppression with a comment, or report the pattern for recognition.

Enterprise Trust​

Is Skylos enterprise-ready?​

Skylos Cloud is ready for a security-team pilot and controlled enterprise evaluation.

Current enterprise foundations include:

  • local-first scanning
  • Cloud project governance
  • project API keys
  • GitHub Actions OIDC uploads
  • role-based workspace access
  • audit coverage for mutating governance workflows
  • upload attribution
  • audit export foundations

Full regulated procurement controls such as SAML SSO, SCIM, SOC 2 reporting, DPA automation, public status/SLA, and SIEM streaming are still on the enterprise roadmap.

See Enterprise Trust for the current trust posture.

Does Skylos upload my whole repository?​

Normal skylos . --upload sends scan results and metadata to Skylos Cloud, not the full repository as source blobs.

Uploaded findings can include security-sensitive metadata, file paths, line numbers, rule ids, branch/commit metadata, and contextual evidence needed to explain results. Treat uploaded scan results as sensitive security data.

How do we know who uploaded a scan?​

Skylos Cloud records attribution from the server-side auth path:

  • browser-linked CLI uploads use the linked user and project credential
  • API key uploads use the resolved project key identity
  • GitHub OIDC uploads use verified GitHub OIDC claims and the matched project binding

This means two people can upload from different desktops to the same project, and Cloud still records the resolved project, auth path, repo/project-root context, branch, commit metadata, and upload time.

Quality Gate​

How does the quality gate work?​

The gate compares findings against thresholds in your config:

[tool.skylos.gate]
fail_on_critical = true
max_security = 0
max_quality = 10

If thresholds are exceeded, skylos --gate exits with code 1.

Can I bypass the gate?​

In interactive terminals, you'll be prompted to bypass unless strict = true. In CI/CD, the gate cannot be bypassed.

How do I set up the gate in CI?​

- name: Quality Gate
  run: skylos . --danger --quality --gate

See CI/CD Integration for full examples.

Performance​

How fast is Skylos?​

Codebase SizeTime
10K lines< 2 seconds
100K lines< 10 seconds
1M lines< 60 seconds

Security scanning (--danger) adds ~20% overhead.

How can I make it faster?​

Exclude non-essential folders, scan only changed files, or skip security scanning if you only need dead code detection.

Troubleshooting​

'skylos' command not found​

Ensure you installed it with pip install skylos and your virtual environment is activated. Try python -m skylos.cli . as an alternative.

Analysis takes forever​

You may be scanning a large directory. Use --verbose to check what's being analyzed and add --exclude-folder for large non-source directories.

Getting different results locally vs CI​

Check for different Python versions, exclusion settings, or Skylos versions between environments. Pin the version in CI with pip install skylos==2.6.0.

Error parsing a file​

Skylos requires valid Python syntax. Verify with python -m py_compile path/to/file.py and fix any syntax errors.

AI features not working​

Verify your API key is set (echo $OPENAI_API_KEY), the key is valid, and you have available credits/quota.

More Help​