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 new Copilot sessions consistently use Hawkeye Skill + CLI SOP, complete this once per machine:

1. Build the project:

npm install
npm run build

2. Keep workspace skill and instructions files in place: - .github/skills/hawkeye-agent/SKILL.md - .github/copilot-instructions.md

1. Reload VS Code window.

1. Run setup checks from project root:

npm run check:setup
npm run check:smoke

If both pass, new sessions should reliably trigger Hawkeye flow on install commands.

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

Wire the shipped Claude Code hook 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 (also covers a tool-agnostic shell shim).

🚀 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: Choose mode -> (1) Security report first (2) Direct install now

Developer: 1
Hawkeye: [returns full integrated audit report with policy verdict and remediation]

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

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.

---

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: Approve & Execute: If the package is approved, simply repeat the command or tell Hawkeye to "go ahead." Hawkeye will recognize the package is safe and actually execute the installation.