skillhub/document/docs/02-administration/security/scanner.md

title	sidebar_position	description
Security Scanning	4	Use Skill Scanner to add automated security checks to the skill publish pipeline

Security Scanning

SkillHub can integrate skill-scanner into the publish pipeline to automatically inspect uploaded skill packages and persist the results as security audit records.

Scan Flow

When scanning is enabled, the publish flow becomes:

1. A user publishes a skill package
2. The backend creates a version and moves it to SCANNING
3. The backend enqueues a scan task
4. skill-scanner consumes the task and runs analysis
5. The result is stored in security_audit
6. The version moves to PENDING_REVIEW, or to SCAN_FAILED after final retry exhaustion
7. The existing human review workflow continues afterward

Typical Use Cases

• Add automated risk checks before manual review
• Retain scan results and audit evidence for governance
• Detect suspicious code, leaked secrets, or risky behavior patterns in skill packages

Runtime Modes

Two modes are supported:

• local: the backend passes a filesystem path to the scanner, suitable for shared filesystem setups
• upload: the backend uploads the package archive directly, suitable for Docker, Kubernetes, and split deployments

Recommended usage:

• Local development: prefer local
• Production, Kubernetes, or split services: prefer upload

Key Configuration

Core backend configuration:

skillhub:
  security:
    scanner:
      enabled: false
      base-url: http://localhost:8000
      health-path: /health
      scan-path: /scan-upload
      mode: upload
      connect-timeout-ms: 5000
      read-timeout-ms: 300000
      retry-max-attempts: 3

Common environment variables:

• SKILLHUB_SECURITY_SCANNER_ENABLED
• SKILLHUB_SECURITY_SCANNER_URL
• SKILLHUB_SECURITY_SCANNER_MODE
• SKILLHUB_SCAN_STREAM_KEY
• SKILLHUB_SCAN_STREAM_GROUP

How To Verify

After enabling scanning, validate it with these steps:

1. Publish a test skill package
2. Confirm the version first moves to SCANNING
3. Confirm a security_audit record is created
4. Confirm the version eventually moves to PENDING_REVIEW or SCAN_FAILED
5. Call the security audit API to inspect the result

GET /api/v1/skills/{skillId}/versions/{versionId}/security-audit

Result Fields

Security audit results usually include:

• scanId
• scannerType
• verdict
• isSafe
• maxSeverity
• findingsCount
• findings
• scanDurationSeconds
• scannedAt

Deployment Recommendations

• Keep scanning disabled at first in local environments, then enable it after the main flow is stable
• Use upload mode in Kubernetes to avoid relying on a shared writable filesystem
• In production, keep scan results alongside human review records as governance evidence

Next Steps

• Review Workflow - Understand the approval flow after scanning
• Deployment Configuration - Review deployment-related settings