Simple AI Gateway Tool

A policy-enforced gateway that mediates AI agent access to external systems such as Jira, Jenkins, and databases. The AI acts as a requesting client: every action must pass through server-side policy evaluation, authorization, and audit before reaching the target system.

Stack: Java 21, Spring Boot, Gradle, Docker

For architectural decisions and rationale, see ARCHITECTURAL-FACTS.md.

Quick Start

Prerequisites

• Java 21 (build)
• Docker & Docker Compose (run)

Build & Run

./start.sh

This builds the bootJar, starts the gateway in Docker, and verifies it's healthy at http://localhost:8080.

To stop:

./stop.sh

Manual Build

./gradlew :app-monolith:bootJar --no-daemon
docker compose up --build -d

How It Works

AI Client / Agent   -->  POST /api/gateway/execute  -->  Gateway
                                                          |
                                          Authorization --+
                                          JWT Auth -------+
                                          Fraud Detection +
                                          Policy Engine --+
                                          Audit ----------+
                                                          |
                                                     Tool Provider (Jira / Jenkins / DB)

1. The AI authenticates via /api/auth/token and receives a scoped JWT
2. Every tool invocation goes through /api/gateway/execute
3. The gateway evaluates policies (deny-overrides), checks authorization, runs fraud detection, and logs an audit entry
4. Only if all checks pass does the request reach the tool provider

Tool Surface

The gateway currently exposes these tool operations through its HTTP interface:

Tool	Description
jira.getTicket / jira.createTicket	Read and create Jira tickets
jenkins.deploy	Trigger Jenkins deployments
db.queryReadonly	Execute read-only DB queries
db.runLiquibase	Run Liquibase migrations
db.executeScript	Execute DB scripts (intentionally blocked by policy in the default config)

Demo Scenes

The scenes/ directory contains a guided walkthrough. Each scene demonstrates a specific policy behavior. Run them in order: scene 00 sets up authentication, then each subsequent scene builds on the previous.

Setup

#	Scene	File
00	Setup: Authenticate & Start Gateway	00-setup.md

Policy Decisions

#	Scene	Expected Decision
01	Read-only database query	ALLOW
02	Production deployment (requires approval)	REQUIRE_APPROVAL
03	Scope mismatch (insufficient permissions)	DENY
04	Blocked tool (db.executeScript)	DENY
05	Rate limit exceeded	DENY
06	Outside time window (business hours)	DENY
07	Argument validation (project not in allowlist)	DENY

Fraud Detection

#	Scene	Attack Vector
08	SQL injection in query arguments	08-fraud-sql-injection.md
09	Prompt injection in tool arguments	09-fraud-prompt-injection.md
10	Repeated denial pattern (hammering)	10-fraud-repeated-denial.md

Observability

#	Scene	What It Shows
11	Audit trail query	11-audit-trail.md
12	Hot-reload policies without restart	12-hot-reload-policies.md

Policy Configuration

Policies live in files/config/policies.yaml. The format uses a Kubernetes-style manifest with 6 rule types: scope, environment, argument_allowlist, time_window, rate_limit, block.

Policies support hot-reload — edit the file and the gateway picks up changes without restart (see scene 12).

Project Structure

app-monolith/                    # Composition root (Spring Boot app)
adapter-http-gateway/            # HTTP orchestration (/api/gateway/*)
adapter-http-security-infra/     # JWT auth & Spring Security
gateway-module-policy/           # Policy engine (6 rule evaluators)
gateway-module-authorization/    # Scope-to-permission mapping
gateway-module-audit/            # Audit trail (NDJSON, TSDB-ready)
gateway-module-fraud-detection/  # SQL injection, prompt injection, pattern detection
gateway-module-tool-registry/    # Tool autodiscovery
gateway-providers/               # Jira, Jenkins, Database providers
scenes/                          # Guided demo walkthrough
files/config/                    # policies.yaml