Hawkeye Agent

✅ Requirements

Before setup, make sure your local environment meets the following:

• Node.js 18+ (Node.js 20+ recommended)
• npm 9+
• Internet access to https://api.osv.dev
• Internet access to https://api.deps.dev
• Internet access to https://osv.dev
• Internet access to https://deps.dev
• VS Code with Copilot Chat (for conversational skill workflow)

---

1. Build from Source

Run Hawkeye from source by cloning the repository:

git clone https://github.com/ryanHwH20/oss-hawkeye-agent.git
cd oss-hawkeye-agent
npm install
npm run build

2. One-Time Developer Setup (Recommended)

To make Codex, Claude Code, and Copilot sessions consistently use the same Hawkeye workflow, complete this once per checkout:

1. Build the project:

npm install
npm run build:mcp

2. Keep the committed project Skill and MCP configuration files in place. Trust the repository and approve its MCP server when your host asks.

1. Restart the agent conversation so it discovers the project Skill.

1. Run setup checks from project root:

npm run check:setup
npm run check:smoke

If both pass, use $oss-hawkeye in Codex, /oss-hawkeye in Claude Code, or @oss-hawkeye in VS Code Copilot.

Gate AI-Agent Installs (PreToolUse hook)

check-command audits the package(s) a shell command would install, so an AI coding agent can be blocked before it adds a risky dependency:

hawkeye check-command "npm install express@4.16.0"   # exit 0 pass / 1 blocked / 2 error

The result leads with a decision-first Install Plan — a one-page table plus a single copy-paste safe install command that pins every fixable package to a verified-clean version. Packages no version swap can rescue are listed separately, so the command never silently ships something unsafe:

```markdown

Install Plan

✅ Safe install command

​

npm install axios@1.16.0 lodash@4.18.0
​

Wire the shipped [Claude Code adapter](adapters/claude-code.mjs) into `~/.claude/settings.json` and the agent literally can't run a blocked `npm install` — a true gate, not a prompt nudge. See **[docs/INTEGRATIONS.md](docs/INTEGRATIONS.md)** (also covers a tool-agnostic shell shim, and the shared `adapters/` architecture other AI tools plug into).

For an interactive, vendor-neutral agent tool, build and register the optional
local MCP adapter (Node.js 20+):

It exposes assessment and resumable next-action tools to Codex, Claude Code, and other MCP clients without executing the proposed install. MCP complements rather than replaces the enforcing hook or shell shim. See PR5 MCP UAT for setup and seven-ecosystem verification.

🚀 Quick Start

Example Output

```

.github/workflows/security.yml (example)

- name: Audit a dependency with Hawkeye run: node dist/cli.js NPM express 4.16.0 --sarif > hawkeye.sarif - name: Upload to GitHub Code Scanning uses: github/codeql-action/upload-sarif@v3 with: sarif_file: hawkeye.sarif ```

When a data source is unreachable, Hawkeye fails closed (exit 1) rather than reporting a package as clean — so a CI gate never green-lights an unverifiable package.

Example Conversation Flow

Developer: Is lodash safe for our project?
Hawkeye: [returns full integrated audit report]

Developer: npm install lodash
Hawkeye: [checks the exact command and returns the policy verdict and next action]

You can ask Hawkeye to: - Audit before install: npm install express - Check package security: "Is lodash safe?", "Are there any vulnerabilities in requests?" - Inquire about licensing: "What is the license of this package?", "Can we use GPL packages?" - Find secure alternatives: "What are the safe alternatives to moment?" - Check enterprise policy: "What is the company's open source policy?"

---

🏛️ Policy Configuration

Hawkeye uses a .audit-agent.yaml file in the working directory to enforce compliance. If none is found, it falls back to the built-in policy.json.

policy:
  organizationName: "Your Organization"
  blockedLicenses:
    - "GPL-2.0-only"
    - "GPL-3.0-only"
    - "AGPL-3.0-only"
    - "SSPL-1.0"
    - "BUSL-1.1"
  minScorecardScore: 4.0
  blockVulnerabilities: true
  minBlockingSeverity: "MEDIUM"   # CRITICAL | HIGH | MEDIUM | LOW — lowest severity that blocks (default MEDIUM)
  blockDeprecated: true
  blockTyposquats: true            # block names that look like a typosquat of a popular package (default true)
  exceptionFormUrl: "https://your-org.com/oss-exception-request"

---

Quick Reference

🤖 Skill + CLI Integration

Hawkeye is designed to run as a local CLI auditor while AI assistant behavior is controlled by workspace skill instructions.

CLI Commands

Use the built CLI directly for deterministic security checks:

node dist/cli.js NPM lodash
node dist/cli.js PYPI requests 2.31.0
node dist/cli.js GO github.com/gin-gonic/gin

Agent-facing API (schema v1)

An integration should not have to reverse-engineer CLI prose to decide what an agent may do next. assessAction() returns one versioned, machine-actionable contract for every agent surface:

import { assessAction } from 'oss-hawkeye-agent';

const assessment = await assessAction({
  kind: 'shell_command',
  command: 'npm install lodash@4.17.20',
  cwd: process.cwd(),
});

Applicable install actions return an AdmissionDecision with raw and effective verdicts, structured findings and evidence references, policy identity, governed overrides, verified remediation, and one deterministic next action. Commands outside the supported install surface return not_applicable rather than claiming a security SAFE verdict. See Agent Harness Architecture.

Integrations that need the package-level trust boundary can use the Decision Kernel directly:

import {
  collectPackageEvidence,
  evaluatePackage,
  loadPolicy,
} from 'oss-hawkeye-agent';

const evidence = await collectPackageEvidence({
  system: 'PYPI',
  name: 'requests',
  version: '2.32.3',
});
const result = evaluatePackage(evidence, loadPolicy());

Long-running agent integrations can preserve and resume the decision workflow:

import { createRun, nextAction, submitResult } from 'oss-hawkeye-agent';

const state = createRun(intent, policyRef, { runId: 'run-123' });
const action = nextAction(state);
const updated = submitResult(state, action.id, actionResult);

The versioned state records bounded attempts and action history without storing conversation or hidden model state. Only the expected action result can advance the workflow; approval requests never let an agent approve itself. The Harness does not execute commands—normal Hawkeye enforcement remains authoritative. See Agent Harness Architecture and the PR3 maintainer UAT.

3. Single Package Audit (CLI)

You can run the built CLI directly to get a full enterprise-grade security report:

node dist/cli.js NPM express 4.16.0
node dist/cli.js PYPI requests 2.31.0
node dist/cli.js MAVEN org.springframework.boot:spring-boot 3.5.8

Package Audit: express@4.16.0 (NPM)

### ❌ BLOCKED — Security Policy Violation

.github/workflows/hawkeye.yml

name: Hawkeye on: [pull_request] permissions: contents: read pull-requests: write # post the PR comment security-events: write # upload SARIF jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: ryanHwH20/oss-hawkeye-agent@v1 with: path: . comment: 'true' # sticky PR comment (default true) upload-sarif: 'true' # GitHub code scanning (default true) fail-on-block: 'true' # fail the job when BLOCKED/UNVERIFIED (default true) ```

The comment renders as a scan summary — e.g. hawkeye scan . --comment locally produces the same Markdown.

---

`@oss-hawkeye` in VS Code Chat

The VS Code adapter exposes Hawkeye as an explicit chat participant while keeping security decisions in the same Runtime and Harness:

@oss-hawkeye /check npm install axios@1.7.2
@oss-hawkeye /status
@oss-hawkeye /explain
@oss-hawkeye /fix
@oss-hawkeye /policy
@oss-hawkeye /scan

@oss-hawkeye selects the security participant; slash commands select a specific operation. The participant never executes an install or creates an approval. Build a locally installable VSIX with npm run package:vscode, and see the PR4 maintainer UAT for installation and rollback.

Demo GIF (Question -> Integrated Report)

The demo below shows the signature experience: ask a question, get one integrated security report.

<img src="./docs/assets/hawkeye-conversation-demo.gif" alt="Hawkeye Conversational Demo" width="640" />

Hawkeye's primary interaction model is a two-step conversational guardrail built for real developer conversations:

1. Step 1: Intercept & Audit: When you attempt to install a package or ask about it, Hawkeye intercepts the intent, runs the CLI audit flow, and returns a comprehensive security report. It will not install the package yet. 2. Step 2: Act on the canonical result: Only SAFE returns an allowed action. BLOCKED, UNKNOWN, and NOT_APPLICABLE are never converted into approval, and execution remains a separate host action subject to normal enforcement.