@asterlabs/scanner

Security scanner for AI agent skills. Provides pattern-based security scanning and scoring for skill packages before they are published to the ask registry.

Installation

npm install @asterlabs/scanner

Quick Start

import { scan } from "@asterlabs/scanner";

const content = `
# My Skill

Instructions for my skill...
`;

const result = scan(content);
console.log(`Score: ${result.score}/100`);
console.log(`Passed: ${result.passed}`);
console.log(`Issues: ${result.issues.length}`);

Usage

Basic Scanning

import { Scanner, createScanner, scan } from "@asterlabs/scanner";

// Quick function
const result = scan(content);

// Or create a reusable scanner instance
const scanner = createScanner();
const result = scanner.scan(content);

// Check if content passes
if (scanner.passes(content)) {
  console.log("Content is safe!");
}

Custom Options

import { Scanner } from "@asterlabs/scanner";

const scanner = new Scanner({
  // Minimum score to pass (default: 50)
  minScore: 70,

  // Categories to scan (default: all)
  categories: ["secrets", "code_execution"],

  // Severity levels to include (default: all)
  severities: ["critical", "high"],

  // Custom patterns
  customPatterns: [
    {
      id: "custom-pattern",
      pattern: /FORBIDDEN_WORD/gi,
      type: "custom_issue",
      category: "secrets",
      severity: "high",
      message: "Forbidden word detected",
    },
  ],
});

Scan Result

interface ScanResult {
  // Security score (0-100)
  score: number;

  // Pass/fail status
  passed: boolean;

  // List of detected issues
  issues: SecurityIssue[];

  // Counts by severity
  summary: {
    critical: number;
    high: number;
    medium: number;
    low: number;
    info: number;
    total: number;
  };

  // Scan metadata
  metadata: {
    scannedAt: string;
    contentLength: number;
    lineCount: number;
    scanDurationMs: number;
  };
}

Security Issue

interface SecurityIssue {
  patternId: string;
  type: string;
  category: PatternCategory;
  severity: Severity;
  message: string;
  line: number;
  column?: number;
  match: string;
  recommendation?: string;
}

Security Patterns

The scanner detects the following categories of issues:

Secrets

• Hardcoded API keys
• Hardcoded passwords
• Tokens and secrets
• AWS access keys
• Private keys
• GitHub tokens

Code Execution

• eval() usage
• new Function() constructor
• Command injection
• curl/wget pipe to shell

File System

• Dangerous rm -rf commands
• chmod 777 permissions
• Filesystem formatting
• Direct device writes

Credentials

• /etc/passwd access
• /etc/shadow access
• SSH directory access
• AWS credentials access
• Kubernetes config access

Network

• Listening on all interfaces
• Disabled SSL verification
• Hardcoded authentication

System

• Privilege escalation
• NOPASSWD sudo
• Cron modification
• Firewall changes

Scoring

| Severity | Deduction | | -------- | --------- | | Critical | -25 | | High | -15 | | Medium | -10 | | Low | -5 | | Info | 0 |

Score starts at 100 and cannot go below 0.

Score Ratings

| Score | Rating | | ------ | --------- | | 90-100 | Excellent | | 70-89 | Good | | 50-69 | Fair | | 25-49 | Poor | | 0-24 | Critical |

API

scan(content: string, options?: ScanOptions): ScanResult

Quick function to scan content.

createScanner(options?: ScanOptions): Scanner

Create a new Scanner instance.

class Scanner

• scan(content: string): ScanResult - Scan content
• passes(content: string): boolean - Quick pass/fail check
• getOptions(): ScanOptions - Get current options
• getPatterns(): SecurityPattern[] - Get active patterns

calculateScore(issues: SecurityIssue[]): number

Calculate security score from issues.

SECURITY_PATTERNS: SecurityPattern[]

Array of built-in security patterns.

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage
pnpm test:coverage

License

MIT