126 lines
4.7 KiB
Markdown
126 lines
4.7 KiB
Markdown
# 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](ARCHITECTURAL-FACTS.md).
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Java 21 (build)
|
|
- Docker & Docker Compose (run)
|
|
|
|
### Build & Run
|
|
|
|
```bash
|
|
./start.sh
|
|
```
|
|
|
|
This builds the bootJar, starts the gateway in Docker, and verifies it's healthy at `http://localhost:8080`.
|
|
|
|
To stop:
|
|
|
|
```bash
|
|
./stop.sh
|
|
```
|
|
|
|
### Manual Build
|
|
|
|
```bash
|
|
./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](scenes/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](scenes/08-fraud-sql-injection.md) |
|
|
| 09 | Prompt injection in tool arguments | [09-fraud-prompt-injection.md](scenes/09-fraud-prompt-injection.md) |
|
|
| 10 | Repeated denial pattern (hammering) | [10-fraud-repeated-denial.md](scenes/10-fraud-repeated-denial.md) |
|
|
|
|
### Observability
|
|
|
|
| # | Scene | What It Shows |
|
|
|---|-------|---------------|
|
|
| 11 | Audit trail query | [11-audit-trail.md](scenes/11-audit-trail.md) |
|
|
| 12 | Hot-reload policies without restart | [12-hot-reload-policies.md](scenes/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
|
|
```
|