​

Security Scanning

​

Overview

​

6-Stage Pipeline

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   stage0    │───▶│   stage1    │───▶│   stage2    │───▶│   stage3    │───▶│   stage4    │───▶│   stage5    │
│   INGEST    │    │  STRUCTURE  │    │   STATIC    │    │  INJECTION  │    │   SECRETS   │    │   SUPPLY    │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

​

Stage 0: Ingest

• Download from authorized domains only (Supabase storage)
• Validate tarball size (max 50MB compressed, 50MB extracted)
• Detect zip bombs (compression ratio >100x)
• Reject symlinks, hardlinks, path traversal
• Reject binary executables (.exe, .so, .dll, .pyc, .class)
• Compute SHA-256 hash for each file

• download_failed — Cannot retrieve tarball
• zip_bomb — Compression ratio exceeds 100x
• path_traversal — Archive contains dangerous paths like ../../../etc/passwd
• blocked_file_type — Binary or executable file detected
• size_exceeded — Extracted size exceeds 50MB

# From stage0_ingest.py
MAX_TARBALL_SIZE = 50 * 1024 * 1024  # 50MB
MAX_EXTRACTED_SIZE = 50 * 1024 * 1024  # 50MB
MAX_COMPRESSION_RATIO = 100  # decompressed/compressed

BLOCKED_EXTENSIONS = {
    ".exe", ".so", ".dll", ".dylib", ".wasm",
    ".class", ".pyc", ".pyo", ".jar", ".war",
    ".bin", ".dat",
}

​

Stage 1: Structure

• Required files present (skills.json, SKILL.md)
• File count within limits (max 1000 files)
• No hidden files in unexpected locations
• Valid file extensions (whitelist)
• Manifest schema validation

• missing_manifest — No skills.json found
• missing_skill_md — No SKILL.md found
• file_count_exceeded — More than 1000 files

• suspicious_hidden_file — Hidden file outside expected locations (e.g., .git/)
• unexpected_extension — File extension not in allowlist

​

Stage 2: Static Analysis

• Python AST analysis (detects eval, exec, compile, __import__)
• JavaScript pattern matching (obfuscated code, dynamic requires)
• Dangerous function calls (shell execution, file operations)
• Network operations (HTTP requests, socket connections)
• Subprocess spawning
• Dynamic code generation
• Obfuscation detection (base64, hex encoding)
• Suspicious imports (e.g., ctypes, subprocess, socket)

• arbitrary_code_exec — Use of eval(), exec(), compile()
• shell_injection_risk — Unsafe shell command construction
• unsafe_deserialization — Use of pickle.loads() or similar

• obfuscated_code — Base64-encoded payloads or hex strings
• dynamic_import — Use of __import__() or importlib
• suspicious_network — Network calls to non-declared domains

• subprocess_spawn — Subprocess usage without declaration
• filesystem_write — File writes to sensitive paths

​

Stage 3: Injection Detection

• Prompt injection patterns (“Ignore previous instructions”)
• System prompt extraction attempts
• Role confusion attacks (impersonating user/assistant)
• Instruction override patterns
• Multi-turn attack sequences
• Unicode homoglyphs (lookalike characters)
• Hidden instructions (whitespace tricks, zero-width chars)

• prompt_injection — Direct injection pattern detected
• system_prompt_extraction — Attempts to extract system prompts

• role_confusion — Instructions to change agent role
• instruction_override — Attempts to override core instructions

• unicode_homoglyph — Suspicious lookalike characters
• hidden_instruction — Zero-width or invisible characters

​

Stage 4: Secrets Scanning

• API keys (OpenAI, Anthropic, AWS, GitHub, Stripe, etc.)
• AWS credentials (access keys, secret keys)
• Private keys (RSA, SSH, PGP)
• Database connection strings
• JWT tokens
• Generic high-entropy strings (potential secrets)

• hardcoded_api_key — API key found in code
• hardcoded_aws_credentials — AWS credentials embedded
• private_key_embedded — RSA/SSH private key in code

• database_credentials — DB connection string with password
• jwt_token — Hardcoded JWT

• high_entropy_string — Potential secret (base64, hex)

​

Stage 5: Supply Chain

• Dependency analysis (NPM, PyPI, etc.)
• Known vulnerable packages (CVE database)
• Typosquatting detection (e.g., reqests vs requests)
• Dependency confusion attacks
• Unpinned dependencies
• Deprecated packages

• known_vulnerability — Dependency has published CVE
• typosquatting — Dependency name closely matches popular package

• unpinned_dependency — Version range too broad (e.g., *)
• deprecated_package — Dependency is marked deprecated

• outdated_dependency — Newer version available

​

Verdict Rules

def compute_verdict(stage_results: List[StageResult]) -> ScanVerdict:
    """Compute the final verdict from stage results.

    Rules:
    - 1+ critical findings → FAIL
    - 4+ high findings → FAIL
    - 1-3 high findings → FLAGGED
    - Any medium or low findings → PASS_WITH_NOTES
    - No findings → PASS
    """
    # Aggregate all findings
    all_findings = []
    for stage in stage_results:
        all_findings.extend(stage.findings)

    # Count by severity
    critical_count = sum(1 for f in all_findings if f.severity == "critical")
    high_count = sum(1 for f in all_findings if f.severity == "high")
    medium_count = sum(1 for f in all_findings if f.severity == "medium")
    low_count = sum(1 for f in all_findings if f.severity == "low")

    # Apply verdict rules
    if critical_count > 0:
        return ScanVerdict.FAIL

    if high_count >= 4:
        return ScanVerdict.FAIL

    if high_count > 0:
        return ScanVerdict.FLAGGED

    if medium_count > 0 or low_count > 0:
        return ScanVerdict.PASS_WITH_NOTES

    return ScanVerdict.PASS

​

Verdict Meanings

​

Finding Structure

class Finding(BaseModel):
    """A single security finding from any stage."""

    stage: str = Field(..., description="Stage that produced this finding (stage0-stage5)")
    severity: Literal["critical", "high", "medium", "low"] = Field(
        ..., description="Severity level"
    )
    type: str = Field(..., description="Finding type e.g. 'prompt_injection', 'shell_injection'")
    description: str = Field(..., description="Human-readable description")
    location: Optional[str] = Field(None, description="File:line or path reference")
    confidence: Optional[float] = Field(None, ge=0.0, le=1.0, description="Confidence score 0-1")
    tool: Optional[str] = Field(None, description="Tool or rule that found this")
    evidence: Optional[str] = Field(None, description="Raw snippet or pattern matched")

​

Example Finding

{
  "stage": "stage2",
  "severity": "critical",
  "type": "arbitrary_code_exec",
  "description": "Use of eval() detected — can execute arbitrary code",
  "location": "src/main.py:42",
  "confidence": 1.0,
  "tool": "stage2_static",
  "evidence": "eval(user_input)"
}

​

Audit Score

score = 10.0
score -= (critical_count * 3.0)  # -3 per critical
score -= (high_count * 1.0)      # -1 per high
score -= (medium_count * 0.3)    # -0.3 per medium
score -= (low_count * 0.1)       # -0.1 per low
score = max(0, score)            # Floor at 0

• 10: Perfect — no findings
• 9-10: Excellent — minor notes only
• 7-8: Good — some medium findings
• 5-6: Fair — multiple medium or 1-2 high
• <5: Poor — critical or many high findings

{
  "audit": {
    "min_score": 8.0
  }
}

​

Scan Response

interface ScanResponse {
  scan_id: string;                    // UUID of stored scan result
  verdict: "pass" | "pass_with_notes" | "flagged" | "fail";
  findings: Finding[];                // All findings from all stages
  stage_results: StageResult[];       // Per-stage results
  duration_ms: number;                // Total scan time
  file_hashes: Record<string, string>; // SHA-256 per file
}

interface StageResult {
  stage: string;                      // "stage0" - "stage5"
  status: "passed" | "failed" | "errored" | "skipped";
  findings: Finding[];
  duration_ms: number;
  error?: string;                     // Error message if status is "errored"
}

​

Viewing Scan Results

​

CLI

# View security report for a skill
tank audit @tank/google-sheets

# Output:
# @tank/[email protected]
# Verdict: PASS_WITH_NOTES
# Audit Score: 9.2/10
#
# Findings (2):
#   [medium] stage2: subprocess_spawn at src/export.py:15
#   [low] stage5: outdated_dependency — [email protected] (latest: 2.31.0)

​

Web UI

https://tankpkg.dev/skills/@tank/google-sheets

• Verdict badge
• Audit score
• All findings with severity, location, and evidence
• Stage-by-stage breakdown

​

Best Practices

​

Before Publishing

1. Run local scan (if available):
   tank scan --local
   
2. Review findings before submitting
3. Fix critical and high findings — These will block publishing
4. Document medium/low findings — Explain why they’re safe in your README or SKILL.md

​

Handling Flagged Verdicts

1. Submit for review:
   tank publish --request-review
   
2. Provide context — Explain why high findings are false positives
3. Wait for approval — Registry admins will review and approve/reject

​

False Positives

# This triggers "dynamic_import" (medium severity)
try:
    import numpy as np
except ImportError:
    np = None

## Security Notes

This skill uses dynamic imports for optional dependencies (numpy, pandas).
The scanner flags this as `dynamic_import` (medium severity), but it is
safe because:
- Imports are hardcoded (no user input)
- Used only for optional features
- Falls back gracefully if not installed

​

Next Steps

• Permissions — Declare permissions correctly to avoid findings
• Manifest — Configure audit.min_score for dependencies
• Lockfile — Audit scores are stored in skills.lock