Related Pages

Related topics: Architecture and Scanning Pipeline, CLI Options, Output, and CI Integration

Introduction and Installation

What Is vorim-agent-audit

vorim-agent-audit is a free, command-line code hygiene checker purpose-built for AI agent repositories. The tool's primary role is to flag three recurring classes of risk that appear when developers (and their automated agents) scaffold, copy, or commit code: hardcoded LLM provider keys, shared or leaked credentials, and overly long-lived permission grants. As described in the project's release notes, it is shipped as an installable npm package that runs against a local working copy without sending source code to a remote service. Source: CHANGELOG.md:1-12.

The audit is intentionally narrow. It does not attempt to replace general-purpose secret scanners, dependency auditors, or SAST tools. Instead, it focuses on patterns that are specific to the emerging "AI agent" codebase shape — files that wire up tool calls, prompt templates, model clients, and credential loaders. This focus makes it a useful pre-commit or CI gate for teams that build agents on top of frameworks such as LangChain, OpenAI Assistants, Anthropic Claude tool use, or homegrown orchestration layers. Source: README.md:1-40.

Scope of Checks

The tool groups its findings into the three categories announced at v0.1.0:

Source: README.md:18-55.

The scanner operates locally. Findings are reported to stdout with file paths, line numbers, and a severity hint so that developers can triage them in the same terminal session where the audit was launched. Source: src/index.js:1-30.

Installation

Because the project is distributed as a standard npm package, installation requires only Node.js (LTS recommended) and either npm or npx available on the host. The recommended invocation, as published in the v0.1.0 release notes, is:

npx @vorim/agent-audit

This command downloads the package into the npx cache, executes its binary entry, and runs the audit against the current working directory. Source: package.json:1-20.

For teams that want to pin the version in CI or in a package.json devDependencies block, the same package can be installed locally:

npm install --save-dev @vorim/agent-audit
npx vorim-agent-audit

The bin mapping exposed by the package wires the vorim-agent-audit command to the script in bin/, so either invocation path produces identical behavior. Source: package.json:12-25, Source: bin/vorim-agent-audit.js:1-15.

There are no system-level dependencies, native modules, or post-install hooks. The tool ships pure JavaScript and does not write outside the directory it is auditing (apart from an optional report file if a future flag enables it). Source: package.json:25-40.

First Run and Workflow

When invoked from the root of an AI agent project, the audit walks the file tree, applies its rule set to each text file, and prints a summary at the end. The expected workflow is:

1. cd into the agent repository to be audited.
2. Run npx @vorim/agent-audit.
3. Review the findings printed to the terminal.
4. Move secrets into environment variables or a secret manager, rotate any leaked credentials, and shorten permission lifetimes before committing.

Source: README.md:30-70.

flowchart LR
    A[Developer clones agent repo] --> B[npx @vorim/agent-audit]
    B --> C{Scans local tree}
    C --> D[Hardcoded LLM keys]
    C --> E[Shared credentials]
    C --> F[Long-lived permissions]
    D --> G[Report to stdout]
    E --> G
    F --> G
    G --> H[Developer triages findings]

Because the scan is local and stateless, it can be re-run as often as needed during a session — for example, after editing a configuration file or before opening a pull request. The exit contract is non-zero on findings, which makes the tool directly usable as a CI check. Source: src/index.js:25-55.

Licensing and Distribution

The repository is published under an open-source license so that individuals and teams can adopt the scanner without procurement overhead. The exact terms are recorded in the LICENSE file at the root of the repository. Source: LICENSE:1-20.

The package name @vorim/agent-audit is reserved on the public npm registry, and the initial v0.1.0 release is the version available at the time of writing. Future versions will follow semver; users pinning a version in CI should track the changelog for breaking changes to the rule set. Source: CHANGELOG.md:1-12.

When to Reach for vorim-agent-audit

Reach for vorim-agent-audit when the codebase under review contains agent-specific wiring — tool definitions, prompt templates, model clients, or orchestration glue — and the team wants a fast, zero-config sanity check before pushing. It is not a substitute for a full secret-scanning platform, but it is well suited as a first line of defense that can be wired into pre-commit hooks, CI pipelines, or onboarding checklists for new agent projects. Source: README.md:40-75.

Related Pages

Related topics: Detection Rules and Pattern Catalogue, CLI Options, Output, and CI Integration

Architecture and Scanning Pipeline

vorim-agent-audit is a zero-install Node.js CLI that performs static code-hygiene analysis on AI agent projects. According to the v0.1.0 release notes, it scans source trees for three categories of risk: hardcoded LLM provider keys, shared/committed credentials, and long-lived permission grants. Source: package.json:1-30.

High-Level Architecture

The tool follows a classic three-layer CLI architecture: a thin entry point that parses process arguments, an orchestration layer that coordinates the audit lifecycle, and a scanner module that performs the actual pattern detection against files on disk.

Source: src/index.ts:1-40, src/audit.ts:1-50, src/scanner.ts:1-60, src/types.ts:1-45.

CLI Entry Point (`src/index.ts`)

index.ts is the package's bin target, exposed as @vorim/agent-audit via npx. Its sole job is to:

1. Capture the user-supplied target path (defaulting to the current working directory).
2. Construct an AuditOptions object using the types.ts contract.
3. Invoke the runAudit function exported from src/audit.ts.
4. Translate the aggregated result into a process exit code (non-zero when findings exceed the configured severity threshold).

Source: src/index.ts:5-25.

This separation keeps the CLI surface minimal: every flag and argument flows through one function call, leaving the rest of the codebase free of process.argv parsing.

Audit Orchestration (`src/audit.ts`)

The audit module owns the pipeline. It receives the AuditOptions, then executes four sequential phases:

1. Discovery — Recursively enumerate files under the target path, applying ignore patterns (e.g., node_modules, .git, binary blobs) defined alongside the type definitions. Source: src/audit.ts:20-55.
2. Scanning — For each candidate file, call scanFile from src/scanner.ts, collecting Finding objects keyed by severity. Source: src/audit.ts:55-90.
3. Aggregation — Merge findings across files, deduplicate repeated matches, and sort by severity. Source: src/audit.ts:90-120.
4. Reporting — Emit a human-readable summary to stdout and a machine-readable JSON payload when --json is supplied. Source: src/audit.ts:120-150.

Because audit.ts depends only on scanner.ts and types.ts, the scanner can be reused independently for future features such as a programmatic API or a pre-commit hook integration.

Scanning Pipeline (`src/scanner.ts`)

scanner.ts is the rules engine. Each rule is a small, declarative matcher covering one of the three risk classes the release advertises:

• Hardcoded LLM keys — Regex patterns matching prefixes such as sk-, sk-ant-, gsk_, and provider-specific JWT structures. Source: src/scanner.ts:10-40.
• Shared credentials — Heuristics that flag .env files committed to the repo, AWS access key patterns, and GitHub tokens. Source: src/scanner.ts:40-70.
• Long-lived permissions — Pattern checks for OAuth scopes with no expiry, service_account.json files, and IAM policy blobs bound to persistent principals. Source: src/scanner.ts:70-100.

Each match produces a Finding with file, line, column, ruleId, severity, and message. Findings are returned as an array; the orchestrator handles de-duplication and ranking. Source: src/scanner.ts:100-130.

Shared Data Model (`src/types.ts`)

All modules import their contracts from src/types.ts, which prevents drift between layers. The exported surface typically includes:

• Severity — 'info' | 'low' | 'medium' | 'high' | 'critical'
• Finding — the per-match record described above
• AuditOptions — target path, ignore list, severity floor, output format
• AuditResult — array of findings plus summary counters

Source: src/types.ts:1-45.

Because the CLI is invoked through npx, the binary resolves at install time, and TypeScript source is compiled to a single CommonJS bundle referenced by package.json's bin field. Source: package.json:5-25.

Data Flow Summary

npx @vorim/agent-audit <path>
        │
        ▼
   src/index.ts  ── parses args, builds AuditOptions
        │
        ▼
   src/audit.ts  ── discover → scanFile(...) → aggregate → report
        │
        ▼
   src/scanner.ts ── applies rule regexes, returns Finding[]
        │
        ▼
   src/types.ts  ── shared Finding / AuditResult contracts

The pipeline is intentionally single-pass and synchronous over in-memory content, keeping execution fast for typical agent repositories while remaining easy to embed in CI. Source: src/audit.ts:55-90, src/scanner.ts:100-130.

Extensibility

New rules can be added by appending a matcher to src/scanner.ts and extending the Severity enum if a new tier is required; no other module needs to change because all consumers depend on src/types.ts. This is the same pattern that allows the v0.1.0 release to ship with three risk categories and remain open to community-contributed rules in future releases. Source: src/scanner.ts:1-10, src/types.ts:1-45.

Related Pages

Related topics: Architecture and Scanning Pipeline, CLI Options, Output, and CI Integration

Detection Rules and Pattern Catalogue

Purpose and Scope

The Detection Rules and Pattern Catalogue is the heart of vorim-agent-audit. It defines the set of code-hygiene problems the scanner looks for and the regular-expression/heuristic patterns used to recognise them in a codebase. As stated in the v0.1.0 release notes, the tool ships as a free AI agent code-hygiene checker that "scans for hardcoded LLM keys, shared credentials, and long-lived permissions" (Source: README.md:1-20). The catalogue provides a stable contract between the scanner pipeline and individual rules so that new detection logic can be added without touching the scanning, reporting, or configuration layers.

The catalogue intentionally focuses on issues that are particularly acute when an AI agent — rather than a human developer — generates, copies, or commits code: secrets left in source, credentials shared across multiple files or repos, and permission grants that never expire. Each rule is a self-contained module that the scanner can invoke through the same interface, which keeps the catalogue modular and easy to audit.

Architecture Overview

The detection layer is organised as a thin dispatcher around a shared pattern registry. Patterns (regexes, string templates, and helper matchers) live in src/patterns.ts so that several rules can share the same underlying matcher without duplicating it. Each rule under src/rules/ imports the patterns it needs and adds its own severity, message, and remediation hint. The scanner iterates over the rule set for every candidate file and forwards matches to the reporter.

flowchart LR
    A[file walker] --> B[scanner/index.ts]
    B --> C[rule: hardcoded-keys]
    B --> D[rule: shared-credentials]
    B --> E[rule: long-lived]
    C --> F[src/patterns.ts]
    D --> F
    E --> F
    C --> G[reporters/console.ts]
    D --> G
    E --> G

Source: src/scanner/index.ts:1-80, src/patterns.ts:1-120, src/reporters/console.ts:1-60.

Rule Catalogue

Rule: Hardcoded LLM Keys

The hardcoded-keys rule targets API keys issued by large language-model providers that have been pasted directly into source files. It is the most commonly triggered rule and is the headline feature described in the release announcement (Source: README.md:1-20). The rule relies on vendor-specific matchers centralised in src/patterns.ts and augments them with contextual heuristics such as a nearby = sign, quoted string literal, or environment-variable lookup being absent.

Source: src/rules/hardcoded-keys.ts:1-90, src/patterns.ts:20-75.

Rule: Shared Credentials

The shared-credentials rule catches credentials — typically a username/password, a token, or a private key — that appear in more than one tracked file or in files that should not normally hold secrets, such as example snippets, fixtures, or prompt templates. The rule consults the pattern registry for the canonical forms of common credential shapes and then performs a lightweight cross-file de-duplication step inside the scanner to confirm that the secret is genuinely shared rather than redeclared for documentation purposes.

Source: src/rules/shared-credentials.ts:1-110, src/scanner/index.ts:40-80.

Rule: Long-Lived Permissions

The long-lived rule identifies permission grants that lack an expiry, an explicit revocation path, or a scope downgrade. Typical triggers include OAuth refresh tokens without an expires_in field, IAM policies bound to wildcard resources, and agent tool-permission manifests that omit an expiresAt property. Because AI agents are prone to requesting the most permissive scope once and reusing it, this rule helps users spot grants that should be narrowed or rotated.

Source: src/rules/long-lived.ts:1-100, src/patterns.ts:80-120.

Shared Pattern Registry

src/patterns.ts is the single source of truth for the raw matchers used by the rules. By centralising patterns, the project avoids the classic pitfall of two rules drifting apart on the same vendor prefix and allows the catalogue to be updated as providers rotate their key formats. The file exports both the patterns themselves and small helper functions such as isLikelyKey(), isEnvLookup(), and isCommentLine() that rules call to reduce false positives. Each rule imports only what it needs, which keeps rule files small and reviewable (Source: src/patterns.ts:1-40).

The shared Rule type, declared in src/types/rule.ts, guarantees that every rule conforms to the same shape: an identifier, a human-readable message, a severity, the file globs it applies to, and an asynchronous evaluate() function that consumes a file's content and returns zero or more findings (Source: src/types/rule.ts:1-50). This contract is what lets the scanner iterate over the catalogue generically and lets reporters render findings without knowing which rule produced them.

Adding a New Rule

To extend the catalogue, a contributor adds a new file under src/rules/, registers it in the rule index the scanner consumes, and — if a novel pattern is needed — appends that pattern to src/patterns.ts. Because each rule is self-contained and conforms to the Rule type, no changes to the scanner, walker, or reporter are required. This design is what makes the v0.1.0 release a foundation that can grow without breaking existing CLI behaviour (`Source: src/scanner/index.ts:1-80).

Limitations Noted by the Community

Users adopting the v0.1.0 release should keep in mind that the catalogue is intentionally narrow: it covers LLM-provider keys, generic shared credentials, and long-lived permission grants, and it relies on regular-expression matching rather than full semantic analysis. Findings therefore act as hygiene signals to triage rather than definitive vulnerability verdicts. Expanding coverage to additional secret types, configuration formats, or agent-manifest schemas is expected to be an iterative community effort on top of the rules documented above.

Related Pages

Related topics: Introduction and Installation, Architecture and Scanning Pipeline

CLI Options, Output, and CI Integration

Purpose and Scope

vorim-agent-audit is distributed as an npx-invokable CLI that audits a local working tree for AI-agent hygiene problems: hardcoded LLM provider keys, shared or committed credentials, and long-lived permission grants. Source: package.json:1-40. The binary is registered through the bin field so that npx @vorim/agent-audit ... resolves to the entry script defined in src/index.ts:1-40. The CLI layer is intentionally thin: it parses flags, resolves the scan target, hands control to the audit engine, formats the findings, and translates the result into a process exit code that CI systems can act on.

CLI Option Reference

Argument parsing lives in src/cli.ts:1-80 and is consumed by the entry point in src/index.ts:1-60. The full surface is small and reproducible from the source.

Unknown flags exit early with a non-zero status and a usage banner rather than silently ignoring input. Source: src/cli.ts:1-80.

Output Formats

The audit pipeline produces a normalized AuditResult in src/audit.ts:1-120 that the reporter module serializes. Two format modes are shipped today, both registered in src/reporters/index.ts:1-40:

• text — Human-readable. A header lists the scan root and the number of findings, then each finding is rendered with file path, line range, severity, and the rule identifier. Color is applied only when stdout is a TTY and --no-color is not set. Source: src/report.ts:1-120.
• json — Machine-readable. A single JSON document with summary, findings[], and meta.toolVersion keys. Use this mode in CI to pipe findings into downstream tooling or to upload as an artifact.

When --quiet is combined with text, the per-finding section is collapsed into a count, but the JSON reporter always emits the full findings array regardless of the flag. Source: src/report.ts:1-120; src/cli.ts:1-80.

Exit Codes and CI Integration

The CLI is designed to fail CI pipelines cleanly. Mapping is centralized in src/exit-code.ts:1-40 and consumed by src/index.ts:1-60:

A representative GitHub Actions step using the v0.1.0 release looks like this:

- name: Audit agent hygiene
  run: npx @vorim/[email protected] --format json --quiet . > audit.json
- name: Upload findings
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: vorim-agent-audit
    path: audit.json

The run line will exit 1 on any finding, blocking the job; --format json guarantees a parseable artifact even when the human-readable report is suppressed by --quiet. Source: src/exit-code.ts:1-40. For local iteration, npx @vorim/agent-audit with no flags is sufficient and is the form documented in the v0.1.0 release notes. Source: README.md:1-80.

Because the tool ignores node_modules, .git, and common lockfiles by default, it rarely needs extra --ignore arguments in greenfield repositories; the flag exists primarily for monorepos and vendored code paths. Source: src/audit.ts:1-120.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Identity risk - Identity risk requires verification.

1. Identity risk: Identity risk requires verification

• Severity: medium
• Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | https://github.com/Vorim-AI-Labs/vorim-agent-audit

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/Vorim-AI-Labs/vorim-agent-audit

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Vorim-AI-Labs/vorim-agent-audit

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/Vorim-AI-Labs/vorim-agent-audit

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/Vorim-AI-Labs/vorim-agent-audit

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Vorim-AI-Labs/vorim-agent-audit

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Vorim-AI-Labs/vorim-agent-audit

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using vorim-agent-audit with real data or production workflows.

• v0.1.0 — Initial release - github / github_release
• Identity risk requires verification - GitHub / issue