npm package: @opena2a/semantic-engine
Description: Semantic analysis engine for AI agent security scanning
Author: OpenA2A
Latest version: 0.1.1
Deprecated: Merged into hackmyagent@0.8.0. Use hackmyagent/semantic instead.

# @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

```bash
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

```typescript
import { LLMAnalyzer } from '@opena2a/semantic-engine';

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

## Usage

```typescript
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](https://oasb.ai) 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