awslabs / awslabs/agent-plugins

RFC: Add a HOL Guard AWS operations safety plugin

Open
#258 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
893
Forks
155
Avg merge
5d 20h
Merged PRs (30d)
7

Description

## Summary

Propose a first-class `hol-guard` plugin for Agent Plugins for AWS that installs and invokes HOL Guard as a security gate for AI-assisted AWS operations. The plugin would package guidance and hooks/skills for Claude Code, Codex, and Cursor where supported, while keeping HOL Guard as the enforcement component rather than reimplementing policy in this repository.

HOL Guard already has AWS command-cloud coverage and local harness enforcement. This RFC asks whether that capability is a fit for this repository before any implementation work, per the new-plugin contribution policy.

## Use case

AI agents working with AWS can reach mutating or cost-bearing CLI/API operations. A reusable plugin could give users one installable path to set up HOL Guard, verify protection status, review approvals/evidence, and keep deny/review/error outcomes from being treated as normal successful execution. The primary use case is safer AWS operations initiated from supported local agent harnesses, not a generic AWS policy framework.

## Proposal

If maintainers approve the direction, I would contribute a focused plugin that:

- installs or verifies the real `hol-guard` CLI instead of embedding a separate enforcement engine;
- uses HOL Guard's existing AWS command-cloud coverage and supported harness setup;
- provides agent instructions for `hol-guard status`, `detect`, `doctor`, approvals, receipts/evidence, and guarded harness execution;
- treats deny, unresolved review, and Guard errors as blocking outcomes for protected work;
- includes Claude Code/Codex/Cursor packaging only where the repository's existing plugin conventions and HOL Guard's supported harness behavior line up;
- documents the boundary clearly: this plugin would not claim universal interception of every AWS SDK/API call or unsupported harness.

Implementation would follow the repository's current plugin layout and generated Codex manifest flow, with `mise build` and existing validation before PR.

## Out of scope

- Replacing IAM, SCPs, Organizations policy, CloudTrail, or AWS-native security controls.
- Adding a second policy engine inside Agent Plugins for AWS.
- Claiming unsupported harnesses are intercepted.
- Guard Cloud being required for local protection.
- A PR before this RFC is triaged and approved.

## Potential challenges

The main design question is where HOL Guard should sit relative to existing per-harness hooks so a protected action is gated exactly once and failure modes are unambiguous. Another is keeping the plugin useful across Claude Code, Codex, and Cursor without overstating identical hook semantics. I would keep the first implementation narrow and test deny/review/error paths against concrete AWS CLI examples.

## Dependencies and Integrations

- HOL Guard: https://github.com/hashgraph-online/hol-guard
- HOL Guard Agent Skill/plugin packaging: https://github.com/hashgraph-online/hol-guard-plugin
- Existing AWS command-cloud coverage: https://github.com/hashgraph-online/hol-guard/blob/release/3.0/docs/guard/command-cloud-extension-coverage.md

HOL Guard remains an external dependency; this repository would package the integration rather than vendor the runtime.

## Alternative solutions

Document a manual HOL Guard setup outside the plugin marketplace, or rely only on IAM/AWS-native controls. Those remain useful, but they do not provide the same portable agent-side approval/evidence workflow or one-click plugin distribution. The RFC would let maintainers decide whether official packaging here adds enough value.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the repository's existing plugin layout and generated Codex manifest flow, then read HOL Guard's docs/guard/command-cloud-extension-coverage.md and supported harness behavior. Resolve the hook placement and Claude Code/Codex/Cursor scope with maintainers before implementation. Done means an approved narrow design that passes mise build and existing validation.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws
Domain
cloud, security, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.