---
title: "Build a Security Audit Extension"
source: https://docs.autohand.ai/tutorials/extensions/security-audit-extension
---

# Build the Security Audit extension

Combine dependency and source-pattern audits with a focused security reviewer, while proving that installation, agent allowlists, and useful intent never bypass runtime authorization.

## Pattern under test

`autohand.security-audit` contributes two tools and one agent. It demonstrates the difference between validating a handler's shape and approving an actual invocation in a real repository.

``` text
autohand.security-audit/
  autohand.extension.json
  README.md
  tools/dependency-audit.json
  tools/suspicious-patterns.json
  agents/security-reviewer.md
```

## Create the manifest

``` json
{
  "$schema": "https://raw.githubusercontent.com/autohandai/code-extensions/main/schema/autohand.extension.schema.json",
  "schemaVersion": 1,
  "extensionApi": 1,
  "id": "autohand.security-audit",
  "name": "Security Audit",
  "version": "1.0.0",
  "description": "Audit dependencies and review suspicious execution patterns.",
  "license": "Apache-2.0",
  "repository": "https://github.com/autohandai/code-extensions",
  "contributes": {
    "tools": ["tools/dependency-audit.json", "tools/suspicious-patterns.json"],
    "agents": ["agents/security-reviewer.md"]
  }
}
```

## Add the dependency audit

``` json
{
  "name": "audit_bun_dependencies",
  "description": "Run the Bun dependency vulnerability audit",
  "parameters": {
    "type": "object",
    "properties": {}
  },
  "handler": "bun audit",
  "source": "user"
}
```

This tool has no inputs because the active workspace supplies context. It may use the network and read lockfiles when invoked. Document those operational effects even though the command does not mutate source.

## Add suspicious-pattern discovery

``` json
{
  "name": "find_suspicious_patterns",
  "description": "Find common dynamic execution patterns under a tracked path",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Repository-relative file or directory"
      }
    },
    "required": ["path"]
  },
  "handler": "git grep -n -E 'eval\\(|child_process|exec\\(' -- {{path}}",
  "source": "user"
}
```

Pattern matches are leads, not vulnerabilities. The specialist must trace input, privilege, and exploitability before assigning severity.

## Add the security reviewer

``` markdown
---
description: Review concrete security boundaries with evidence and exploitability context
tools: read_file, fff_grep, audit_bun_dependencies, find_suspicious_patterns
---
Trace untrusted input to privileged behavior. Prioritize authorization bypasses,
command injection, path traversal, unsafe deserialization, secret exposure, and
dependency risk. Report only evidence-backed findings with severity, affected
path, exploit preconditions, and a focused mitigation.
```

The prompt explicitly rejects pattern-only findings. This reduces false positives without weakening the tool's ability to gather broad leads.

## Validate without executing audits

``` bash
autohand extensions validate ./autohand.security-audit --json
autohand extensions install ./autohand.security-audit --link
autohand extensions show autohand.security-audit
autohand extensions doctor
```

Watch the terminal and network during validation if you want additional assurance: neither `bun audit` nor `git grep` should run. Installation reads, validates, and links package files only.

## Exercise normal authorization

Use a disposable Bun repository with a lockfile and a small fixture containing a safe `child_process` use. Ask:

``` text
Delegate to security-reviewer. Audit dependencies and inspect src/ for dynamic
execution patterns. For every candidate, trace whether untrusted input can reach
the privileged action. Return evidence and make no edits.
```

1.  Confirm each shell action goes through the configured approval path.
2.  Deny the network-backed audit once and verify no automatic bypass.
3.  Approve the source scan and verify the path value is the one requested.
4.  Confirm the reviewer labels safe, fixed-command process spawning as context rather than automatically critical.

## Prove immutable security behavior

Create a private negative fixture whose handler contains a command pattern rejected by Autohand's meta-tool safety rules. Add it to a duplicate test package, then run validation. The package should fail before installation.

Do not publish dangerous handler examples in a real extension. The point is to prove that a package cannot opt out of the safety validator or add an approval-bypass field—strict schemas reject unknown fields.

## Clean up

``` bash
autohand extensions disable autohand.security-audit
autohand extensions show autohand.security-audit
autohand extensions remove autohand.security-audit --yes
```

Review the linked source after removal. Autohand removes only the registered link and state, never the authored directory.