SUS
sus
guides

OpenCode

Integrate sus with OpenCode plugins to automatically scan packages installed by AI agents

OpenCode's plugin system lets you extend and control agent behavior using JavaScript or TypeScript. By using the tool.execute.before hook, you can automatically route all package installations through sus for security scanning.

Why Use Plugins?

When AI agents install packages autonomously, they don't verify package integrity or check for known vulnerabilities. This makes them vulnerable to:

  • Typosquatting - installing lodashs instead of lodash
  • Supply chain attacks - compromised packages like event-stream
  • Malicious install scripts - packages that execute code during installation

With sus plugins, every npm install, yarn add, pnpm add, or bun add command is intercepted and routed through sus first.

Prerequisites

Setup

OpenCode plugins are JavaScript or TypeScript files placed in the .opencode/plugins/ directory.

Create the plugin

Create .opencode/plugins/sus-gateway.ts:

TYPESCRIPT
import type { Plugin } from "@opencode-ai/plugin"
 
const INSTALL_PATTERN = /^(npm (i|install|add)|yarn add|pnpm (add|i|install)|bun (add|i|install)|pip install|cargo add) (.+)$/
const UNINSTALL_PATTERN = /^(npm (uninstall|rm)|yarn remove|pnpm (rm|remove)|bun (rm|remove)|pip uninstall|cargo remove) (.+)$/
 
export const SusGatewayPlugin: Plugin = async ({ client }) => {
  await client.app.log({
    service: "sus-gateway",
    level: "info",
    message: "sus gateway plugin loaded",
  })
 
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool !== "bash") return
 
      const cmd = output.args.command
 
      const installMatch = cmd.match(INSTALL_PATTERN)
      if (installMatch) {
        const pkg = installMatch[6]
        throw new Error(`Use \`sus add ${pkg}\` instead for security scanning.`)
      }
 
      const uninstallMatch = cmd.match(UNINSTALL_PATTERN)
      if (uninstallMatch) {
        const pkg = uninstallMatch[5]
        throw new Error(`Use \`sus remove ${pkg}\` instead.`)
      }
    },
  }
}

That's it—OpenCode automatically loads plugins from this directory at startup.

JavaScript version

If you prefer plain JavaScript, create .opencode/plugins/sus-gateway.js:

JAVASCRIPT
const INSTALL_PATTERN = /^(npm (i|install|add)|yarn add|pnpm (add|i|install)|bun (add|i|install)|pip install|cargo add) (.+)$/
const UNINSTALL_PATTERN = /^(npm (uninstall|rm)|yarn remove|pnpm (rm|remove)|bun (rm|remove)|pip uninstall|cargo remove) (.+)$/
 
export const SusGatewayPlugin = async ({ client }) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool !== "bash") return
 
      const cmd = output.args.command
 
      const installMatch = cmd.match(INSTALL_PATTERN)
      if (installMatch) {
        const pkg = installMatch[6]
        throw new Error(`Use \`sus add ${pkg}\` instead for security scanning.`)
      }
 
      const uninstallMatch = cmd.match(UNINSTALL_PATTERN)
      if (uninstallMatch) {
        const pkg = uninstallMatch[5]
        throw new Error(`Use \`sus remove ${pkg}\` instead.`)
      }
    },
  }
}

How It Works

When OpenCode tries to run a package install command:

100%
  1. OpenCode attempts npm install express
  2. Plugin intercepts via tool.execute.before
  3. Plugin throws an Error with instructions to use sus
  4. OpenCode follows the instruction and runs sus add express
  5. sus scans the package for vulnerabilities
  6. If safe, sus installs using your detected package manager

Command Mapping

The plugin intercepts these commands and routes them through sus:

Original Commandsus Equivalent
npm install pkgsus add pkg
yarn add pkgsus add pkg
pnpm add pkgsus add pkg
bun add pkgsus add pkg
pip install pkgsus add pkg
cargo add pkgsus add pkg

Commands without specific packages (like npm install to install from package.json) are allowed through.

Testing the Integration

Ask OpenCode to install a package:

Text
Install the express package

You should see the plugin intercept the command and instruct OpenCode to use sus instead:

Bash
🔍 checking express@4.21.0...
✅ not sus
   ├─ publisher: expressjs (verified)
   ├─ downloads: 32M/week
   ├─ cves: 0
   └─ install scripts: none
📦 installed
📝 updated AGENTS.md docs index

Global Configuration

To apply the sus plugin to all your projects, place it in the global plugins directory:

Bash
mkdir -p ~/.config/opencode/plugins

Then copy the plugin file to ~/.config/opencode/plugins/sus-gateway.ts.

Using npm Packages

You can also publish and install the plugin via npm. Add it to your OpenCode config:

JSON
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["sus-gateway"]
}

Troubleshooting

Plugin not loading

  1. Verify the plugin file exists at .opencode/plugins/sus-gateway.ts
  2. Check that the file exports a named function (not default export)
  3. Restart OpenCode after adding the plugin

Check plugin logs

Add logging to debug your plugin:

TYPESCRIPT
await client.app.log({
  service: "sus-gateway",
  level: "debug",
  message: "Intercepted command",
  extra: { command: cmd },
})

TypeScript errors

If using TypeScript, install the plugin types:

Bash
npm install -D @opencode-ai/plugin

Or add the types to your project's .opencode/package.json:

JSON
{
  "devDependencies": {
    "@opencode-ai/plugin": "latest"
  }
}

Next Steps