Skip to main content

Skylos Workflow Guide

Dead code and security scanner for Python. Follow the steps in order.

Part 1: Getting Started​

Step 1: Install​

pip install skylos

Verify it worked:

skylos --version

Step 2: Run Your First Scan​

Go to your Python project:

cd /path/to/your/project
skylos .

You'll see a list of unused functions and imports.

Step 3: Understand the Output​

Each finding has a confidence score (0-100). Higher = more certain it's dead.

────────────────── Unused Functions ──────────────────
#   Name              Location        Conf
1   old_handler       app.py:16       90%    ← Safe to delete
2   maybe_used        utils.py:42     60%    ← Review first

Rule of thumb:

  • 90-100%: Delete it
  • 60-89%: Look at it first
  • Below 60%: Probably a false positive

Step 4: Remove Dead Code​

Option A: Manual

Open the file, delete the code yourself.

Option B: Interactive Mode

skylos . -i

Use arrow keys to select, spacebar to toggle, enter to confirm.

Preview first without changing anything:

skylos . -i --dry-run

Step 5: Add Security + Quality Scans​

skylos . --danger --secrets --quality
FlagWhat it finds
--dangerSQL injection, command injection, unsafe eval, weak crypto
--secretsHardcoded API keys, passwords, private keys
--qualityComplex functions, deep nesting, too many arguments

You're done with the basics. Everything below is optional.

Part 2: Skylos Cloud (Dashboard + History)​

Cloud gives you:

  • Dashboard to view all scans
  • Scan history
  • Team-wide suppressions (Pro)
  • PR blocking that developers can't bypass (Pro)

Step 1: Create a Project​

  1. Go to skylos.dev
  2. Sign in with GitHub
  3. Create a project
  4. Go to Dashboard → Settings
  5. Copy your API token

Step 2: Connect Your Machine​

skylos sync connect

Paste your token when prompted. This saves it to ~/.skylos/credentials.json.

Now you can upload scans:

skylos . --upload                # Scan + upload results
skylos . --danger --upload       # Security scan + upload

View results at: https://skylos.dev/dashboard

Part 3: Understand the Flags​

FlagWhat it does
--dangerSecurity vulnerabilities (SQLi, command injection, unsafe eval)
--secretsHardcoded API keys, passwords, private keys
--qualityCode complexity, deep nesting, long functions
--uploadSend results to Skylos Cloud
--strictExit code 1 if gate fails (use with --upload in CI)
--gateExit code 1 if gate fails (local only, no upload)
--forceBypass quality gate (emergency override)

Part 4: CI/CD Setup​

skylos sync setup

This wizard will:

  1. Connect to Skylos Cloud (if not already)
  2. Ask what you want to install:
    • Git hooks — blocks git push if scan fails
    • Pre-commit config — blocks git commit if scan fails
    • GitHub Actions — blocks PR merges if scan fails

Just answer the prompts.

Option B: Manual GitHub Actions​

Create .github/workflows/skylos.yml:

name: Skylos Quality Gate

on:
  pull_request:
    branches: [main, master]

jobs:
  skylos:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install skylos
      - name: Run Skylos
        env:
          SKYLOS_TOKEN: ${{ secrets.SKYLOS_TOKEN }}
        run: skylos . --danger --upload --strict

Then add your token to GitHub:

  1. Go to your repo → Settings → Secrets and variables → Actions
  2. Click New repository secret
  3. Name: SKYLOS_TOKEN
  4. Value: your token from Skylos dashboard

What --strict Does​

FlagBehavior
--uploadUpload results to dashboard. If gate fails, shows warning but continues.
--upload --strictUpload results. If gate fails, exits with code 1 (blocks CI).
--gateLocal only. Exits with code 1 if gate fails. No upload.

Part 5: Install GitHub App (Pro — Enforced Checks)​

The GitHub App creates status checks that cannot be bypassed by deleting workflow files.

Step A: Install the App​

  1. Go to Skylos Dashboard → Settings → GitHub Integration
  2. Click Install GitHub App
  3. Select your repository
  4. Click Install

Step B: Protect Your Branch​

In your GitHub repo:

  1. Go to Settings → Branches
  2. Click Add branch protection rule
  3. Branch name pattern: main
  4. Check Require status checks to pass before merging
  5. Search for and select Skylos Quality Gate
  6. Click Create

Now PRs cannot merge until Skylos passes. No exceptions.

Part 6: Sync Team Config (Pro)​

Pull shared suppressions and policies:

skylos sync pull

Creates:

  • .skylos/config.yaml — quality thresholds
  • .skylos/suppressions.json — team-wide false positive rules

Free vs Pro​

FeatureFreeProEnterprise
Local scans✅✅✅
Upload to dashboard✅✅✅
Scan history1050010,000
GitHub Actions (--strict)✅✅✅
GitHub App (enforced checks)❌✅✅
PR diff checks❌✅✅
Team suppressions❌✅✅
Override failed gates❌✅✅
Slack/Discord alerts❌✅✅
SARIF import❌✅✅

GitHub Actions vs GitHub App:

  • Actions — Uses --strict to exit with code 1. Developers can delete the workflow file to bypass.
  • App — Creates a GitHub status check via the skylos-gate app. Cannot be bypassed.
  • Override: Manually approve a failed gate in the dashboard (emergency bypass with audit trail).
  • PR diff checks: Marks findings as "new" (in changed lines) or "legacy" (existed before).

Part 7: Handling False Positives​

Option 1: Inline Comment​

def dynamic_handler():  # pragma: no skylos
    pass

Option 2: Whitelist (Local)​

skylos whitelist 'handle_*'
skylos whitelist 'visit_*' --reason "AST visitor pattern"

This saves to pyproject.toml.

Option 3: Suppressions (Cloud - Pro)​

In the dashboard, click "Suppress" on any finding. This syncs to your team via:

skylos sync pull

Part 8: AI-Powered Analysis​

Setup​

You can run skylos key to run an interactive setup or the manual way below.

export OPENAI_API_KEY="sk-..."
# or
export ANTHROPIC_API_KEY="sk-ant-..."

Run AI Analysis​

skylos agent analyze .          # Hybrid static + AI
skylos agent analyze . --fix    # AI auto-fix
skylos agent review             # Only changed files (for PRs)

Use Local LLMs (No API Key)​

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5-coder:7b

# Run with local model
skylos agent analyze . \
  --provider openai \
  --base-url http://localhost:11434/v1 \
  --model qwen2.5-coder:7b

Cheatsheet​

I want to...Command
Find dead codeskylos .
Find security issuesskylos . --danger
Find hardcoded secretsskylos . --secrets
Check code qualityskylos . --quality
Run all scansskylos . --danger --secrets --quality
Remove code interactivelyskylos . -i
Preview without changingskylos . -i --dry-run
Upload to cloudskylos . --upload
Upload + block on failskylos . --upload --strict
Local gate (no upload)skylos . --gate
One-command CI setupskylos sync setup
Connect to cloudskylos sync connect
Check connectionskylos sync status
Pull team configskylos sync pull
Disconnectskylos sync disconnect
AI analysisskylos agent analyze .
AI auto-fixskylos agent analyze . --fix
Launch web UIskylos run
Add to whitelistskylos whitelist 'pattern'
View whitelistskylos whitelist --show
Lower confidence thresholdskylos . -c 30
Export JSONskylos . --json
Save to fileskylos . -o report.txt

Troubleshooting​

"Q: No token found"

skylos sync connect

"Q: Invalid API token"

Your token expired or was rotated. Get a new one from Dashboard → Settings, then:

skylos sync connect

"Q: Quality gate failed but continuing"

You're on Free plan. Gate shows the failure but doesn't block. Upgrade to Pro or use --strict in CI.

"Q: Nothing showed up"

Your code might be clean. Or lower the threshold:

skylos . -c 30

"Q: Too many false positives"

Raise the threshold or whitelist patterns:

skylos . -c 80
skylos whitelist 'handle_*'

Getting Help​