Oconee Runtime logoOconee RuntimeEnterprise AI Governance

Free and open source

Find governance gaps before your AI agents act

A free CLI that scans your repository and the AI coding-agent configuration around it, then reports where an agent’s permitted actions exceed what the project actually needs. Runs entirely on your machine. No account, no signup, no telemetry.

git clone https://github.com/oconeesoftware/oconee-scan cd oconee-scan npm install && npm run build node dist/cli/index.js

Currently installed from source while the npm package is being prepared. Requires Node.js 18.17 or later. No account, no sign-up.

View on GitHub

Apache-2.0 licensed. Zero runtime dependencies. Works on macOS, Linux and Windows.

What this is, and what it is not

This is a point-in-time assessment. It reads configuration and reports what an agent would be allowed to do in your repository right now.

It is not runtime enforcement. It does not sit between an agent and its actions, it cannot block anything, and a clean report is not evidence that agent activity is governed — only that no configured risk indicators were detected at the moment you ran it.

What it checks

Eight categories of AI agent governance risk

Every finding carries a rule ID, severity, confidence, the evidence behind it, the affected path, and a specific recommendation.

Agent Configuration

Permission modes that bypass prompts, wildcard tool grants, bypass flags committed into automation, hooks that run shell commands, and policy files that are malformed enough to silently stop applying.

Command Execution

Destructive commands sitting in an allow-list, shell access granted with no command constraint, unbounded network egress, and package installs that hand code execution to whatever the agent decides to fetch.

File Access

Write grants with no path constraint, agent scope extended to directories outside the repository, and sensitive paths that no deny rule covers.

Repository Risk

Infrastructure-as-code, CI/CD pipelines, production deployment manifests and container builds. Not defects — context. The same agent permissions carry very different consequences in an infrastructure repository.

Credential Exposure

Environment files, private key material, provider credential files, and text matching known credential formats. The scanner reports the pattern class and location. It never captures the value.

MCP / Tool Access

Servers allowed wholesale rather than tool by tool, write-capable tools on an auto-approve list, plaintext transports to remote hosts, filesystem servers rooted at a home directory, and unpinned package-runner launches.

Approval Controls

Policies with no deny list, no action class routed to a human, agent configuration that lives only in a local settings file, and non-interactive CI runs where nobody can answer a prompt.

Auditability

No record of what agents did, no stated governance policy, no code ownership on the paths that decide what agents may do, and no route for reporting a problem.

Example

What a scan looks like

Terminal output by default. Add --json for a machine-readable report, or --verbose for the evidence and recommendation behind every finding.

Oconee AI Agent Risk Scanner

Repository: example-project

AI Agent Risk Score: 67/100
Risk Level: High

Findings

HIGH
MCP-003 Broad MCP tool permissions
  An MCP server exposes write-capable tools that are auto-approved.
  Actions taken through those tools reach external systems with no
  approval step and, in most hosts, no local audit record.
  .mcp.json  ·  confidence: high  ·  MCP / Tool Access

MEDIUM
AGENT-006 Shell execution capability detected
  Agent configuration permits shell-related functionality. Shell access
  is the broadest action surface an agent can hold.
  .claude/settings.json  ·  confidence: high  ·  Agent Configuration

LOW
AUDIT-002 No local agent governance policy detected

Summary

  Critical  0
  High      2
  Medium    3
  Low       2

Recommended next steps:
  1. Review high-risk MCP permissions
  2. Restrict agent access to sensitive resources
  3. Introduce context-aware action policies

Privacy

Everything runs locally

You are being asked to run an unfamiliar tool against a private repository. These are the guarantees that come with it, and each one is enforced by a test you can read in the repository.

No network access

The package contains no outbound network code. No API call, no version check, no telemetry, no analytics — not by default, not at all.

Nothing leaves your machine

No source code, file contents, secrets, file paths, repository names, findings or scores are transmitted anywhere. Output goes to your terminal, or to the file you name.

Secret values are never captured

When a credential pattern is detected, the scanner records the pattern class, the file path and the line number. The matched text never reaches a finding, a terminal or a report.

Nothing is executed

The scanner never runs a command it finds in your configuration, never starts an MCP server, and never executes project code. It reads files as text and data.

Nothing is modified

Every filesystem operation is a read. Symlinks are indexed but never traversed, so a scan cannot escape the directory you point it at.

No account required

The scanner is free, Apache-2.0 licensed, and fully useful on its own. It does not ask you to sign in, and it never will.

The source is on GitHub. The safety tests live in test/safety.test.ts.

Scoring

How the risk score is calculated

Written out so you can check it. A score you cannot reproduce is a score you cannot argue with internally, which makes it useless in the meeting where it matters.

The score runs from 0 to 100, where higher means greater governance risk. It is computed from the findings alone, with no hidden inputs.

Step 1 — weight each finding

Points are the severity weight multiplied by a confidence factor: high confidence 1.0, medium 0.8, low 0.5. Informational findings contribute nothing.

40

Critical

20

High

8

Medium

3

Low

0

Info

Step 2 — cap each category at 35 points

Points are summed within each of the eight categories, then capped. A repository with thirty low-confidence credential matches cannot outscore one with a genuine permission bypass.

Step 3 — sum the capped categories and clamp to 0–100

0–9

Minimal

10–29

Low

30–54

Moderate

55–79

High

80–100

Critical

The JSON report includes a per-category breakdown of raw and capped points, so you can see exactly what drove the number. The score is not a compliance grade and not a probability of compromise. It is a way to see which gaps are largest, and to watch the number move as you close them.

The model

Where a scan stops, and governance begins

Every agent action is one decision: can this actor, through this agent, take this action, on this resource, in this context?

  1. Actor
  2. Agent
  3. Action
  4. Resource
  5. Context
  6. Policy
  7. Decision
  8. Evidence

The scanner reads the Policy end of that chain. It can tell you which actions your configuration permits, which resources are in reach, and where the policy has no answer at all.

What it cannot do is stand at the point of action. It never sees a real Decision, and it produces no Evidence that an action was evaluated — because by the time you read the report, nothing has been evaluated at all.

Questions

About the scanner

What does the AI Agent Risk Scanner check?

It reads the AI coding-agent configuration in a repository — Claude Code settings, MCP server definitions, Cursor rules, VS Code workspace settings and GitHub Copilot instruction files — plus repository context like CI/CD pipelines, infrastructure-as-code and credential file patterns. It then reports where an agent's permitted actions exceed what the project needs, across eight categories.

Does the scanner send my code or my results anywhere?

No. The scanner makes no network requests of any kind. There is no telemetry, no version check and no analytics in the package. No source code, file contents, secrets, file paths, repository names, findings or scores are transmitted. Output goes to your terminal or to a file you name. If telemetry is ever added it will be explicit opt-in, off by default, and documented before it ships.

Will it print my secrets to the terminal?

No. When a credential pattern is detected, the scanner records the pattern class (for example 'aws-access-key-id'), the file path and the line number. The matched value is never placed into a finding, printed, or written to a report. This is enforced by tests that plant known secrets in a fixture and assert they never appear in any rendered output.

Do I need an Oconee account to use it?

No. The scanner is free and open source under Apache-2.0, works entirely offline, and requires no account, no signup and no API key. It is useful on its own and is designed to stay that way.

Is the risk score a compliance certification?

No. The score is a transparent heuristic computed from the findings, documented in full so you can reproduce it by hand from the JSON report. It is not a probability of compromise, not a compliance grade, and not an absolute measure comparable across unrelated repositories. It is a way to see which governance gaps in your repository are largest, and to watch the number move as you close them.

How is the risk score calculated?

Each finding contributes severity weight multiplied by a confidence factor: critical 40, high 20, medium 8, low 3, info 0; confidence high 1.0, medium 0.8, low 0.5. Points are summed per category, each category is capped at 35 points so one noisy category cannot dominate, and the capped totals are summed and clamped to 0–100. Higher means greater governance risk.

Is this the same as Oconee Runtime?

No. The scanner is a point-in-time assessment: it reads configuration once and reports what an agent would be allowed to do. It cannot block anything. Oconee Runtime is the commercial product that evaluates each agent action against policy at the moment the action is attempted, returns a decision, and keeps that decision as evidence. The scanner tells you where the gaps are; it does not close them.

Can I run it in CI?

Yes. Pass --fail-on high to exit non-zero when a finding at or above that severity exists, or add --json --output report.json to keep a machine-readable record. By default the scanner never fails a build unless you ask it to.

What are the scanner's limitations?

It reads what a policy says, not what an agent actually did. It sees project-scoped configuration only, so user- and machine-level settings that often override project settings are outside the scan. Static credential detection both misses novel formats and flags synthetic values in test fixtures. A clean report means no configured risk indicators were detected at that moment — not that agent activity is governed.

Want continuous policy enforcement instead of a point-in-time scan?

The scanner tells you what your AI agents would be allowed to do. Oconee Runtime governs what they actually do — evaluating each action against policy in context at the moment it is attempted, returning a decision, and keeping that decision as evidence either way.

See Oconee RuntimeGet the scanner on GitHub

The scanner stays free and open source, and works without an Oconee account.

Go deeper

Background on the controls the scanner looks for.