# Agent Security Gateway

MCP‑слой безопасности для AI‑агентов: каждый вызов tool проходит через **allow / confirm / deny** и пишется в audit.

```
Cursor / Claude
      ↓
Agent Security Gateway  ← политики + очередь confirm
      ↓                    + UI аппрувов (:8787)
sandbox tools              + SQLite audit
```

## Быстрый старт

```bash
npm install
npm test
npm run demo          # демо (UI + allow/deny/confirm)
# или
npm run dev           # MCP по stdio + UI для Cursor
```

- UI аппрувов и аудита: http://127.0.0.1:8787  
- MCP работает по **stdio** (логи только в stderr)

### Подключение в Cursor

```json
{
  "mcpServers": {
    "agent-security-gateway": {
      "command": "npm",
      "args": ["run", "dev", "-w", "@agent-security/gateway"],
      "cwd": "/Users/daniildudarev/Downloads/agent-security-gateway"
    }
  }
}
```

### Сценарий confirm

1. Агент вызывает `write_file` → `safe/hello.txt`
2. Открываешь UI → **Approve**
3. Агент смотрит результат через `get_pending` / `list_audit`

## Зачем это нужно

Агенту дают «руки» (tools): файлы, API, БД. Без ограничений он может удалить не то, уйти в цикл или сделать необратимое действие.

Этот gateway стоит **между IDE‑агентом и tools**:

| Решение | Что происходит |
|---------|----------------|
| **allow** | действие выполняется сразу |
| **deny** | блокируется, пишется в audit |
| **confirm** | ждёт человека в UI, потом execute / reject |

По умолчанию — **fail‑closed**: неизвестный tool запрещён.

## Docker

```bash
docker compose up --build
```

UI: http://127.0.0.1:8787

## Переменные окружения

| Переменная | По умолчанию | Назначение |
|------------|--------------|------------|
| `ASG_POLICY_PATH` | `policies/default.yaml` | Файл политик |
| `ASG_APPROVE_HOST` | `127.0.0.1` | Адрес bind (`0.0.0.0` в Docker) |
| `ASG_APPROVE_PORT` | `8787` | Порт UI |
| `ASG_APPROVE_URL` | вычисляется | URL, который видит агент |
| `ASG_DATA_DIR` | `./data` | Каталог SQLite |

## Политики

Файл `policies/default.yaml` — **первое совпадение побеждает**, иначе deny.

| Действие | Путь | Решение |
|----------|------|---------|
| list/read | sandbox | allow |
| write/delete | `prod/**` | deny |
| write/delete | `safe/**` | confirm → UI |
| неизвестный tool | — | deny |

## Sandbox

```
sandbox/
  safe/notes.txt      # безопасный демо‑файл
  prod/users.db       # «прод» — мутации запрещены
```

Все файловые tools работают только внутри `sandbox/`, выход через `..` режется.

## Tools

| Tool | Назначение |
|------|------------|
| `gateway_status` | статус, пути, URL UI |
| `list_dir` / `read_file` | чтение sandbox |
| `write_file` / `delete_file` | мутации (под политикой) |
| `list_pending` / `get_pending` | очередь confirm |
| `list_audit` | история решений |

## Демо

```bash
npm run demo
```

Подробнее: [docs/DEMO.md](./docs/DEMO.md)

> Агентам нужны руки (tools). Руки без ограждения опасны. Этот MCP‑gateway стоит между IDE‑агентом и tools, решает allow/confirm/deny и для рискованных действий ждёт человека — с полным audit trail.

---

# Agent Security Gateway (English)

MCP security layer for AI agents: every tool call goes through **allow / confirm / deny** + audit.

```
Cursor / Claude
      ↓
Agent Security Gateway  ← policy + pending queue
      ↓                    + approve UI (:8787)
sandbox tools              + SQLite audit
```

## Quick start

```bash
npm install
npm test
npm run demo          # demo (UI + allow/deny/confirm)
# or
npm run dev           # MCP stdio + UI for Cursor
```

- Approve / Audit UI: http://127.0.0.1:8787  
- MCP on stdio (logs on stderr)

### Connect from Cursor

```json
{
  "mcpServers": {
    "agent-security-gateway": {
      "command": "npm",
      "args": ["run", "dev", "-w", "@agent-security/gateway"],
      "cwd": "/Users/daniildudarev/Downloads/agent-security-gateway"
    }
  }
}
```

### Confirm flow

1. Agent: `write_file` → `safe/hello.txt`
2. Open UI → **Approve**
3. Agent: `get_pending` / `list_audit`

## Why it exists

Agents get hands (tools): files, APIs, databases. Without guardrails they can delete the wrong thing, loop on expensive calls, or take irreversible actions.

This gateway sits **between the IDE agent and tools**:

| Decision | What happens |
|----------|----------------|
| **allow** | execute immediately |
| **deny** | block + write audit |
| **confirm** | wait for a human in the UI, then execute / reject |

Default is **fail-closed**: unknown tools are denied.

## Docker

```bash
docker compose up --build
```

UI: http://127.0.0.1:8787

## Env

| Variable | Default | Meaning |
|----------|---------|---------|
| `ASG_POLICY_PATH` | `policies/default.yaml` | Policy file |
| `ASG_APPROVE_HOST` | `127.0.0.1` | Bind address (`0.0.0.0` in Docker) |
| `ASG_APPROVE_PORT` | `8787` | Approve UI port |
| `ASG_APPROVE_URL` | derived | URL shown to agents |
| `ASG_DATA_DIR` | `./data` | SQLite DB directory |

## Policy model

`policies/default.yaml` — first match wins, default fail-closed deny.

| Action | Path | Decision |
|--------|------|----------|
| list/read | sandbox | allow |
| write/delete | `prod/**` | deny |
| write/delete | `safe/**` | confirm → human UI |
| unknown tool | — | deny |

## Sandbox

```
sandbox/
  safe/notes.txt      # harmless demo file
  prod/users.db       # fake "prod" — mutations denied
```

All filesystem tools are rooted at `sandbox/` and reject `..` escapes.

## Tools

| Tool | Purpose |
|------|---------|
| `gateway_status` | status, paths, UI URL |
| `list_dir` / `read_file` | read sandbox |
| `write_file` / `delete_file` | mutations (policy-gated) |
| `list_pending` / `get_pending` | confirm queue |
| `list_audit` | decision history |

## Demo

```bash
npm run demo
```

Details: [docs/DEMO.md](./docs/DEMO.md)

> Agents need hands (tools). Hands without a guardrail are dangerous. This MCP gateway sits between the IDE agent and tools, decides allow/confirm/deny, and for risky actions waits for a human — with a full audit trail.