JSPM

@opena2a/semantic-engine

0.1.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 14
  • Score
    100M100P100Q10470F
  • License Apache-2.0

Semantic analysis engine for AI agent security scanning

Package Exports

  • @opena2a/semantic-engine
  • @opena2a/semantic-engine/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@opena2a/semantic-engine) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@opena2a/semantic-engine

Semantic analysis engine for AI agent security scanning. Provides structural (Layer 2) and LLM-powered (Layer 3) analysis on top of the core scanner's regex-based checks (Layer 1).

Zero runtime dependencies. Used internally by @opena2a/core and @opena2a/cli.

Install

npm install @opena2a/semantic-engine

Architecture

Layer Engine Description
1 Core scanner (regex) Pattern matching for known credential formats
2 StructuralAnalyzer Parses configs structurally (JSON/YAML), understands context
3 LLMAnalyzer Calls Anthropic API for nuanced threat analysis

Layer 2: Structural Analysis

Four analyzers that parse security-relevant files and detect issues regex cannot:

CredentialContextAnalyzer

Catches credentials regex misses.

Check Description
SEM-CRED-001 URL-embedded passwords (postgres://admin:password123@host)
SEM-CRED-002 Generic tokens via key-name heuristics ("secret": "abc123...")
SEM-CRED-003 Credentials in agent instruction files (CLAUDE.md, .cursorrules)
SEM-CRED-004 Secrets hardcoded in MCP server env blocks

McpConfigAnalyzer

Deep analysis of MCP server configurations.

Check Description
SEM-MCP-001 Overprivileged filesystem scope (/, /home, /Users)
SEM-MCP-002 Sandbox bypass flags (--no-sandbox, --privileged)
SEM-MCP-003 Secrets exposed in args array (visible to LLM)
SEM-MCP-004 Wildcard permissions (allowedTools: ["*"])
SEM-MCP-005 Attack chains (filesystem + shell + network)
SEM-MCP-006 Large attack surface (>5 MCP servers)

InstructionAnalyzer

Scans agent instruction files for security risks.

Check Description
SEM-INST-001 Overly permissive instructions ("always execute", "never refuse")
SEM-INST-002 Exfiltration-enabling patterns (webhook.site, "send results to")
SEM-INST-003 Missing security boundaries
SEM-INST-004 Large instruction files (>10KB prompt injection surface)

PermissionModelAnalyzer

Analyzes Claude/editor settings for permission issues.

Check Description
SEM-PERM-001 Wildcard permission grants (permissions.allow: ["*"])
SEM-PERM-002 Unrestricted Bash access
SEM-PERM-003 Write access outside project scope

Layer 3: LLM Analysis

Optional LLM-powered analysis using the Anthropic API. Requires ANTHROPIC_API_KEY.

  • Uses Haiku for credential detection (fast, cheap)
  • Uses Sonnet for MCP/instruction analysis (complex reasoning)
  • SHA-256 content-hash cache so repeated scans of unchanged files are free
  • Daily budget cap (default $1/day) to prevent runaway API costs
import { LLMAnalyzer } from '@opena2a/semantic-engine';

const analyzer = new LLMAnalyzer({
  apiKey: process.env.ANTHROPIC_API_KEY,
  budgetPerDay: 1.00, // USD
});

Usage

import { StructuralAnalyzer, toSecurityFindings } from '@opena2a/semantic-engine';

// Run structural analysis on a project directory
const analyzer = new StructuralAnalyzer();
const findings = await analyzer.analyze('/path/to/project');

// Convert to core scanner format
const securityFindings = toSecurityFindings(findings);

File Discovery

The structural analyzer auto-discovers these security-relevant files:

  • Agent instructions: CLAUDE.md, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md
  • MCP configs: mcp.json, .cursor/mcp.json, .vscode/mcp.json
  • Claude settings: .claude/settings.json
  • Env files: .env, .env.local, .env.development, .env.production
  • Config files: config.json, config.yaml, config.yml, settings.json

OASB Mapping

Semantic findings map to OASB benchmark controls:

  • SEM-CRED-* maps to OASB 5.1 (No Hardcoded Credentials)
  • SEM-MCP-* maps to OASB 6.x (Supply Chain Integrity)
  • SEM-INST-* maps to OASB 3.x (Input Security)
  • SEM-PERM-* maps to OASB 2.x (Capability & Authorization)

License

Apache-2.0