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

Column	Meaning
Name	The unused function, import, class, or variable
Location	`file:line` where it's defined
Conf	Confidence score (0–100%) — how certain Skylos is that this code is truly unused. Higher = safer to remove

Rule of thumb:

90–100%: Safe to delete
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

Flag	What it finds
`--danger`	SQL injection, command injection, unsafe eval, weak crypto
`--secrets`	Hardcoded API keys, passwords, private keys
`--quality`	Complex 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 and trend charts
Team collaboration and suppressions (Pro)
PR blocking that developers can't bypass (Pro)
Slack & Discord notifications (Pro)

New Users

Every new account gets 50 starter credits and a 7-day Pro trial — no credit card required.

Step 1: Upload Your First Scan

Just run:

skylos . --upload

That's it. On first run:

Your browser opens automatically
Sign in with GitHub
Pick (or create) a project — one click
Results upload to the dashboard

$ skylos . --upload

Scanning Python files...
✓ Found 15 issues

No Skylos token found. Let's connect to Skylos Cloud.

Opening browser to connect to Skylos Cloud...
Waiting for authentication...

✓ Connected to Skylos Cloud!
  Project:      my-project
  Organization: My Team

Uploading scan results...
✓ Upload complete! View at https://skylos.dev/dashboard

Future uploads work automatically — no prompts, no tokens to copy.

Step 2: Add More Scan Types

skylos . --danger --upload       # Security scan + upload
skylos . --quality --upload      # Quality scan + upload
skylos . --danger --quality --upload  # Everything

View results at: skylos.dev/dashboard

See Authentication for CI/CD setup and advanced options.

Part 3: Understand the Flags

Flag	What it does
`--danger`	Security vulnerabilities (SQLi, command injection, unsafe eval)
`--secrets`	Hardcoded API keys, passwords, private keys
`--quality`	Code complexity, deep nesting, long functions
`--upload`	Send results to Skylos Cloud
`--strict`	Exit code 1 if gate fails (use with `--upload` in CI)
`--gate`	Exit code 1 if gate fails (local only, no upload)
`--force`	Bypass quality gate (emergency override)

Part 4: CI/CD Setup

Option A: GitHub Actions with OIDC (Recommended)

No secrets required! Create .github/workflows/skylos.yml:

name: Skylos Quality Gate

on:
  pull_request:
    branches: [main, master]

permissions:
  contents: read
  id-token: write  # Enables tokenless auth

jobs:
  skylos:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install skylos
      - name: Run Skylos
        run: skylos . --danger --upload

That's it — no tokens, no secrets to configure.

Option B: One-Command Setup

skylos sync setup

This wizard will:

Authenticate with Skylos Cloud (browser opens automatically)
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 C: Manual GitHub Actions (with token)

For explicit token management, 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
        with:
          fetch-depth: 0
      - 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:

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

What `--strict` Does

Flag	Behavior
`--upload`	Upload results to dashboard. If gate fails, shows warning but continues.
`--upload --strict`	Upload results. If gate fails, exits with code 1 (blocks CI).
`--gate`	Local 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

Go to Skylos Dashboard → Settings → GitHub Integration
Click Install GitHub App
Select your repository
Click Install

Step B: Protect Your Branch

In your GitHub repo:

Go to Settings → Branches
Click Add branch protection rule
Branch name pattern: main
Check Require status checks to pass before merging
Search for and select Skylos Quality Gate
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

tip

Every new account gets 50 starter credits and a 7-day Pro trial.

Feature	Free	Pro	Enterprise
Local scans	✅	✅	✅
Upload to dashboard	✅ (1 credit)	✅ (1 credit)	✅ (unlimited)
Projects	1	10	Unlimited
Scan history	10 scans	500 scans	10,000 scans
History retention	7 days	90 days	365 days
GitHub Actions	✅	✅	✅
Server-controlled checks	❌	✅	✅
Full trend charts	❌	✅	✅
Team collaboration	❌	✅	✅
Slack & Discord	❌	✅	✅
Inline PR comments	❌	✅	✅
SARIF export	❌	✅	✅
Custom rules	❌	Up to 50	Unlimited
SSO/SAML	❌	❌	✅

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 scan .             # Hybrid static + AI
skylos agent scan . --fix       # AI auto-fix
skylos agent scan --changed     # 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 scan . \
  --provider openai \
  --base-url http://localhost:11434/v1 \
  --model qwen2.5-coder:7b

Cheatsheet

I want to...	Command
Find dead code	`skylos .`
Find security issues	`skylos . --danger`
Find hardcoded secrets	`skylos . --secrets`
Check code quality	`skylos . --quality`
Run all scans	`skylos . --danger --secrets --quality`
Remove code interactively	`skylos . -i`
Preview without changing	`skylos . -i --dry-run`
Upload to cloud	`skylos . --upload`
Upload + block on fail	`skylos . --upload --strict`
Local gate (no upload)	`skylos . --gate`
One-command CI setup	`skylos sync setup`
Connect to cloud	`skylos sync connect`
Check connection	`skylos sync status`
Pull team config	`skylos sync pull`
Disconnect	`skylos sync disconnect`
AI analysis	`skylos agent scan .`
AI auto-fix	`skylos agent scan . --fix`
Launch web UI	`skylos run`
Add to whitelist	`skylos whitelist 'pattern'`
View whitelist	`skylos whitelist --show`
Lower confidence threshold	`skylos . -c 30`
Export JSON	`skylos . --json`
Save to file	`skylos . -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

GitHub Issues: github.com/duriantaco/skylos/issues
Email: aaronoh2015@gmail.com

Part 1: Getting Started​

Step 1: Install​

Step 2: Run Your First Scan​

Step 3: Understand the Output​

Step 4: Remove Dead Code​

Step 5: Add Security + Quality Scans​

Part 2: Skylos Cloud (Dashboard + History)​

Step 1: Upload Your First Scan​

Step 2: Add More Scan Types​

Part 3: Understand the Flags​

Part 4: CI/CD Setup​

Option A: GitHub Actions with OIDC (Recommended)​

Option B: One-Command Setup​

Option C: Manual GitHub Actions (with token)​

What --strict Does​

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

Step A: Install the App​

Step B: Protect Your Branch​

Part 6: Sync Team Config (Pro)​

Free vs Pro​

Part 7: Handling False Positives​

Option 1: Inline Comment​

Option 2: Whitelist (Local)​

Option 3: Suppressions (Cloud - Pro)​

Part 8: AI-Powered Analysis​

Setup​

Run AI Analysis​

Use Local LLMs (No API Key)​

Cheatsheet​

Troubleshooting​

Getting Help​