hiro-agent 0.1.0__tar.gz

hiro_agent-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/

hiro_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hiro Security, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hiro_agent-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: hiro-agent
+Version: 0.1.0
+Summary: AI security review agent for code, plans, and infrastructure
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: claude-agent-sdk>=0.1.37
+Requires-Dist: click>=8.0
+Requires-Dist: structlog
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hiro-agent
+
+AI security review agent for code, plans, and infrastructure. Integrates with Claude Code, Cursor, VSCode Copilot, and Codex CLI to enforce security reviews before commits and plan finalization.
+
+## Install
+
+```bash
+pip install hiro-agent
+```
+
+## Quick Start
+
+```bash
+# Set up hooks for your AI coding tools
+hiro setup
+
+# Review code changes
+git diff | hiro review-code
+
+# Review an implementation plan
+cat plan.md | hiro review-plan
+
+# Review infrastructure configuration
+hiro review-infra main.tf
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `hiro review-code` | Security review of code changes (stdin: git diff) |
+| `hiro review-plan` | STRIDE threat model review of a plan (stdin) |
+| `hiro review-infra` | IaC security review (file arg or stdin) |
+| `hiro setup` | Auto-detect and configure all AI coding tools |
+| `hiro verify` | Verify hook integrity against installed version |
+
+### Setup Options
+
+```bash
+hiro setup                # Auto-detect all tools
+hiro setup --claude-code  # Claude Code only
+hiro setup --cursor       # Cursor only
+hiro setup --vscode       # VSCode Copilot only
+hiro setup --codex        # Codex CLI only
+```
+
+## Configuration
+
+Set `HIRO_API_KEY` to connect to the Hiro platform for organizational context (security policies, memories, org profile). Without it, reviews still run using your `ANTHROPIC_API_KEY` directly.
+
+```bash
+export HIRO_API_KEY=hiro_ak_...     # Optional: Hiro platform context
+export ANTHROPIC_API_KEY=sk-ant-... # Required if HIRO_API_KEY not set
+```
+
+## How It Works
+
+1. **`hiro setup`** installs hook scripts in `.hiro/hooks/` and configures your AI coding tool to call them
+2. Hooks track file modifications and block commits until `hiro review-code` has run
+3. Hooks track plan creation and block finalization until `hiro review-plan` has run
+4. Review agents use `claude-agent-sdk` to spawn a Claude instance that performs the security review
+5. When connected to Hiro (`HIRO_API_KEY`), reviews are enriched with your org's security policy, accepted risks, and architecture context
+
+## License
+
+MIT

hiro_agent-0.1.0/README.md

@@ -0,0 +1,66 @@
+# hiro-agent
+
+AI security review agent for code, plans, and infrastructure. Integrates with Claude Code, Cursor, VSCode Copilot, and Codex CLI to enforce security reviews before commits and plan finalization.
+
+## Install
+
+```bash
+pip install hiro-agent
+```
+
+## Quick Start
+
+```bash
+# Set up hooks for your AI coding tools
+hiro setup
+
+# Review code changes
+git diff | hiro review-code
+
+# Review an implementation plan
+cat plan.md | hiro review-plan
+
+# Review infrastructure configuration
+hiro review-infra main.tf
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `hiro review-code` | Security review of code changes (stdin: git diff) |
+| `hiro review-plan` | STRIDE threat model review of a plan (stdin) |
+| `hiro review-infra` | IaC security review (file arg or stdin) |
+| `hiro setup` | Auto-detect and configure all AI coding tools |
+| `hiro verify` | Verify hook integrity against installed version |
+
+### Setup Options
+
+```bash
+hiro setup                # Auto-detect all tools
+hiro setup --claude-code  # Claude Code only
+hiro setup --cursor       # Cursor only
+hiro setup --vscode       # VSCode Copilot only
+hiro setup --codex        # Codex CLI only
+```
+
+## Configuration
+
+Set `HIRO_API_KEY` to connect to the Hiro platform for organizational context (security policies, memories, org profile). Without it, reviews still run using your `ANTHROPIC_API_KEY` directly.
+
+```bash
+export HIRO_API_KEY=hiro_ak_...     # Optional: Hiro platform context
+export ANTHROPIC_API_KEY=sk-ant-... # Required if HIRO_API_KEY not set
+```
+
+## How It Works
+
+1. **`hiro setup`** installs hook scripts in `.hiro/hooks/` and configures your AI coding tool to call them
+2. Hooks track file modifications and block commits until `hiro review-code` has run
+3. Hooks track plan creation and block finalization until `hiro review-plan` has run
+4. Review agents use `claude-agent-sdk` to spawn a Claude instance that performs the security review
+5. When connected to Hiro (`HIRO_API_KEY`), reviews are enriched with your org's security policy, accepted risks, and architecture context
+
+## License
+
+MIT

hiro_agent-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "hiro-agent"
+version = "0.1.0"
+description = "AI security review agent for code, plans, and infrastructure"
+requires-python = ">=3.11"
+license = "MIT"
+readme = "README.md"
+dependencies = [
+    "claude-agent-sdk>=0.1.37",
+    "structlog",
+    "click>=8.0",
+]
+
+[project.scripts]
+hiro = "hiro_agent.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hiro_agent"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "strict"
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio"]

hiro_agent-0.1.0/src/hiro_agent/__init__.py

@@ -0,0 +1,3 @@
+"""AI security review agent for code, plans, and infrastructure."""
+
+__version__ = "0.1.0"

hiro_agent-0.1.0/src/hiro_agent/_common.py

@@ -0,0 +1,104 @@
+"""Shared agent runner for local security review agents.
+
+CLAUDECODE="" prevents claude-agent-sdk from detecting a nested Claude Code
+session and rejecting the spawn. This is intentional — the review agent is
+a separate subprocess, not a nested invocation of the caller's session.
+"""
+
+import os
+
+import structlog
+from claude_agent_sdk import (
+    AssistantMessage,
+    ClaudeAgentOptions,
+    TextBlock,
+    query,
+)
+from claude_agent_sdk.types import McpHttpServerConfig
+
+logger = structlog.get_logger(__name__)
+
+# Hardcoded — not configurable to prevent SSRF. HTTPS enforced.
+HIRO_MCP_URL = "https://api.hiro.is/mcp/architect"
+HIRO_BACKEND_URL = "https://api.hiro.is"
+
+
+def _get_mcp_config() -> dict[str, McpHttpServerConfig]:
+    """Build MCP server config for connecting to Hiro.
+
+    Returns an empty dict when HIRO_API_KEY is not set (MCP context
+    tools will be unavailable but the review still runs).
+    """
+    key = os.environ.get("HIRO_API_KEY", "")
+    if not key:
+        return {}
+    return {
+        "hiro": McpHttpServerConfig(
+            url=HIRO_MCP_URL,
+            headers={"Authorization": f"Bearer {key}"},
+        ),
+    }
+
+
+def _get_agent_env() -> dict[str, str]:
+    """Build env vars for the agent subprocess.
+
+    When HIRO_API_KEY is set, route LLM calls through the Hiro backend
+    proxy to Bedrock (keeps source code within AWS infrastructure).
+    Otherwise the agent uses the developer's ANTHROPIC_API_KEY directly.
+    """
+    env: dict[str, str] = {"CLAUDECODE": ""}
+    api_key = os.environ.get("HIRO_API_KEY", "")
+    if api_key:
+        env["ANTHROPIC_BASE_URL"] = f"{HIRO_BACKEND_URL}/api/llm-proxy"
+        env["ANTHROPIC_API_KEY"] = api_key
+    return env
+
+
+async def run_review_agent(
+    prompt: str,
+    system_prompt: str,
+    *,
+    cwd: str | None = None,
+    allowed_tools: list[str] | None = None,
+    max_turns: int = 15,
+) -> str:
+    """Run a local review agent and return its final text output.
+
+    The agent connects to the Hiro MCP server for organizational context
+    (memories, security policy, org profile) and optionally has filesystem
+    access via Read/Grep/Glob tools.
+
+    Only read-only MCP tools are allowed — remember, set_org_context, and
+    forget are explicitly excluded to prevent the review agent from
+    modifying organizational state.
+    """
+    mcp_config = _get_mcp_config()
+
+    # MCP context tools are only available when connected to Hiro
+    mcp_tools = []
+    if mcp_config:
+        mcp_tools = [
+            "mcp__hiro__get_org_context",
+            "mcp__hiro__recall",
+            "mcp__hiro__get_security_policy",
+        ]
+
+    options = ClaudeAgentOptions(
+        cwd=cwd,
+        allowed_tools=(allowed_tools or []) + mcp_tools,
+        system_prompt=system_prompt,
+        mcp_servers=mcp_config,
+        permission_mode="acceptEdits",
+        max_turns=max_turns,
+        env=_get_agent_env(),
+    )
+
+    summary = ""
+    async for message in query(prompt=prompt, options=options):
+        if isinstance(message, AssistantMessage):
+            for block in message.content:
+                if isinstance(block, TextBlock):
+                    summary = block.text
+
+    return summary

hiro_agent-0.1.0/src/hiro_agent/cli.py

@@ -0,0 +1,111 @@
+"""CLI entry point: hiro review-code, review-plan, review-infra, setup, verify."""
+
+import asyncio
+import os
+import sys
+
+import click
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+# 2 MB stdin cap to prevent accidental piping of huge files
+MAX_STDIN_BYTES = 2 * 1024 * 1024
+
+
+def _read_stdin(command_name: str) -> str:
+    """Read stdin with a 2MB size cap."""
+    if sys.stdin.isatty():
+        click.echo(f"Error: No input on stdin. Pipe content to `hiro {command_name}`.", err=True)
+        raise SystemExit(1)
+    data = sys.stdin.buffer.read(MAX_STDIN_BYTES + 1)
+    if len(data) > MAX_STDIN_BYTES:
+        click.echo(
+            f"Error: Input exceeds 2MB limit ({len(data)} bytes). "
+            "Reduce the input size or review files individually.",
+            err=True,
+        )
+        raise SystemExit(1)
+    return data.decode("utf-8", errors="replace")
+
+
+@click.group()
+@click.version_option(package_name="hiro-agent")
+def main() -> None:
+    """Hiro — AI security review agent."""
+
+
+@main.command("review-code")
+@click.option("--context", "-c", default="", help="Additional context about the code.")
+def review_code_cmd(context: str) -> None:
+    """Review code changes for security issues. Reads diff from stdin."""
+    from hiro_agent.review_code import review_code
+
+    diff = _read_stdin("review-code")
+    if not diff.strip():
+        click.echo("Error: Empty input. Pipe a diff: git diff | hiro review-code", err=True)
+        raise SystemExit(1)
+
+    cwd = os.getcwd()
+    result = asyncio.run(review_code(diff, cwd=cwd, context=context))
+    click.echo(result)
+
+
+@main.command("review-plan")
+@click.option("--context", "-c", default="", help="Additional context about the plan.")
+def review_plan_cmd(context: str) -> None:
+    """Review an implementation plan for security concerns. Reads from stdin."""
+    from hiro_agent.review_plan import review_plan
+
+    plan = _read_stdin("review-plan")
+    if not plan.strip():
+        click.echo("Error: Empty input. Pipe a plan: cat plan.md | hiro review-plan", err=True)
+        raise SystemExit(1)
+
+    result = asyncio.run(review_plan(plan, context=context))
+    click.echo(result)
+
+
+@main.command("review-infra")
+@click.argument("filepath", required=False)
+def review_infra_cmd(filepath: str | None) -> None:
+    """Review infrastructure config for security issues. File arg or stdin."""
+    from hiro_agent.review_infra import review_infrastructure
+
+    if filepath:
+        filename = os.path.basename(filepath)
+        filepath = os.path.abspath(filepath)
+        cwd = os.path.dirname(filepath)
+        result = asyncio.run(
+            review_infrastructure(filepath, filename=filename, cwd=cwd)
+        )
+    else:
+        config = _read_stdin("review-infra")
+        if not config.strip():
+            click.echo("Error: Empty input. Usage: hiro review-infra <file>", err=True)
+            raise SystemExit(1)
+        result = asyncio.run(
+            review_infrastructure(config, filename="stdin")
+        )
+
+    click.echo(result)
+
+
+@main.command()
+@click.option("--claude-code", "tools", flag_value="claude-code", help="Claude Code only.")
+@click.option("--cursor", "tools", flag_value="cursor", help="Cursor only.")
+@click.option("--vscode", "tools", flag_value="vscode", help="VSCode Copilot only.")
+@click.option("--codex", "tools", flag_value="codex", help="Codex CLI only.")
+def setup(tools: str | None) -> None:
+    """Configure AI coding tool hooks for security review enforcement."""
+    from hiro_agent.setup_hooks import run_setup
+
+    run_setup(tool_filter=tools)
+
+
+@main.command()
+def verify() -> None:
+    """Verify hook integrity against installed package version."""
+    from hiro_agent.setup_hooks import run_verify
+
+    run_verify()

hiro_agent-0.1.0/src/hiro_agent/hooks/enforce_code_review.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""Enforce Hiro code review before committing.
+
+Tracks whether files have been modified since the last review_code call.
+Blocks git commit until a code review has been run on the changes.
+
+Tool-agnostic: works with Claude Code, Cursor, VSCode Copilot, and
+as a git pre-commit hook. Detects caller format automatically.
+
+State stored in .hiro/.state/ (not tool-specific directories).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+STATE_DIR = Path(".hiro/.state")
+
+
+def _state_path(session_id: str) -> Path:
+    safe = session_id.replace("/", "_")
+    return STATE_DIR / f"code_review_{safe}.json"
+
+
+def _load(session_id: str) -> dict[str, Any]:
+    path = _state_path(session_id)
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except Exception:
+        return {}
+
+
+def _save(session_id: str, state: dict[str, Any]) -> None:
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    os.chmod(STATE_DIR, stat.S_IRWXU)  # 0700
+    state["updated_at"] = int(time.time())
+    path = _state_path(session_id)
+    path.write_text(json.dumps(state))
+    os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)  # 0600
+
+
+def _allow() -> None:
+    print("{}")
+
+
+def _deny(message: str) -> None:
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                },
+                "systemMessage": message,
+            }
+        )
+    )
+
+
+def _is_git_commit(command: str) -> bool:
+    """Check if a bash command is a git commit."""
+    stripped = command.strip()
+    parts = stripped.split("&&")
+    for part in parts:
+        tokens = part.strip().split()
+        if len(tokens) >= 2 and tokens[0] == "git" and tokens[1] == "commit":
+            return True
+    return False
+
+
+def _is_review_command(tool_name: str, tool_input: dict[str, Any]) -> bool:
+    """Check if this is a code review action (MCP tool or CLI command)."""
+    if tool_name == "mcp__hiro__review_code":
+        return True
+    if tool_name == "Bash":
+        cmd = tool_input.get("command", "")
+        # Match both old (hiro_review.review_code) and new (hiro review-code) forms
+        if "hiro_review.review_code" in cmd or "hiro review-code" in cmd:
+            return True
+    return False
+
+
+def main() -> int:
+    try:
+        input_data = json.load(sys.stdin)
+    except Exception:
+        _allow()
+        return 0
+
+    event = input_data.get("hook_event_name", "")
+    session_id = input_data.get("session_id", "default")
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+
+    # --- PostToolUse: track edits and reviews ---
+    if event == "PostToolUse":
+        if tool_name in ("Edit", "Write"):
+            state = _load(session_id)
+            files = state.get("modified_files", [])
+            file_path = tool_input.get("file_path", "")
+            if file_path and file_path not in files:
+                files.append(file_path)
+            state["modified_files"] = files
+            state["needs_review"] = True
+            _save(session_id, state)
+
+        elif _is_review_command(tool_name, tool_input):
+            # Review done — clear the flag
+            state = _load(session_id)
+            state["needs_review"] = False
+            state["modified_files"] = []
+            _save(session_id, state)
+
+        _allow()
+        return 0
+
+    # --- PreToolUse: block git commit if review is pending ---
+    if event == "PreToolUse" and tool_name == "Bash":
+        command = tool_input.get("command", "")
+        if _is_git_commit(command):
+            state = _load(session_id)
+            if state.get("needs_review"):
+                files = state.get("modified_files", [])
+                file_list = ", ".join(files[-5:])
+                if len(files) > 5:
+                    file_list += f" and {len(files) - 5} more"
+                _deny(
+                    f"Commit blocked: {len(files)} file(s) modified since last "
+                    f"security review ({file_list}). Run "
+                    "`git diff | hiro review-code` "
+                    "before committing."
+                )
+                return 0
+
+        _allow()
+        return 0
+
+    _allow()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())