Skip to content
82 changes: 78 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -235,13 +235,83 @@ select_only=true
```

Needs `az login` beforehand, and the signed-in identity mapped as a database
user: `CREATE USER [you@company.com] FROM EXTERNAL PROVIDER;`. Encryption and
certificate verification are forced on for this mode, because an access token is
a bearer credential and an unverified connection hands it to whoever answers.
user. Map a dedicated reader identity, or a group, with `db_datareader` only:

```sql
CREATE USER [argos-readers] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [argos-readers];
```

Do not let Argos sign in as the server's Entra admin: the admin is a member of
`db_owner` in every user database and enters each one as `dbo`, so the only thing
between the agent and a `DELETE` is Argos's filter. Argos checks this on connect
and warns (see the [database role check](docs/guides/security-guide.md#database-role-check)).
Encryption and certificate verification are forced on for this mode, because an
access token is a bearer credential and an unverified connection hands it to
whoever answers.

#### A separate Azure identity for the agent

The Azure CLI keeps its sign-in in a profile directory, `~/.azure` unless
`AZURE_CONFIG_DIR` says otherwise. Sign the reader identity in to a profile of
its own, and start Argos with that variable, so the agent never uses your own,
possibly admin, login:

```bash
export AZURE_CONFIG_DIR="$HOME/.azure-claude-ro"
az login # as the reader identity
claude mcp add argos --scope user -e AZURE_CONFIG_DIR="$HOME/.azure-claude-ro" -- \
node "$(pwd)/dist/cli.js" serve --config "$HOME/.config/argos/config.ini"
```

Your own shell keeps `~/.azure` and your own login. To give one database its own
profile instead of the whole server, set `azure_config_dir` on it:

```ini
[database.azure_sql]
type=mssql
host=your-server.database.windows.net
database=your_database_name
authentication=azure-cli
azure_config_dir=~/.azure-claude-ro
```

Then check who Argos is from inside a session, with `sql_query`:

```sql
SELECT USER_NAME() AS db_user, IS_ROLEMEMBER('db_owner') AS is_owner,
IS_ROLEMEMBER('db_datawriter') AS is_writer;
```

`db_user` should be the reader, and both flags `0`. `sql_test_connection` runs
the same check and says so.

See the [SQL Server guide](docs/databases/sql-server.md#azure-cli-authentication)
for the details, including unattended use.

### Azure Database for PostgreSQL without a password

The same Azure CLI sign-in works for Azure Database for PostgreSQL. The Entra
access token is the password, fetched fresh for every new connection because it
is valid for 5 to 60 minutes.

```ini
[database.azure_pg]
type=postgresql
host=your-server.postgres.database.azure.com
port=5432
database=your_database_name
username=argos-readers
authentication=azure-cli
select_only=true
# azure_tenant_id=00000000-0000-0000-0000-000000000000
```

`username` is the Entra user or group as mapped in the database with
`pgaadauth_create_principal`. TLS with certificate verification is forced, for
the same reason as for Azure SQL. See the
[PostgreSQL guide](docs/databases/postgresql.md#azure-database-for-postgresql-with-azure-cli-authentication).

### Multi-Database Analytics Setup
```ini
[database.transactions]
Expand Down Expand Up @@ -276,7 +346,11 @@ query_timeout=30000

1. **Query validation**: SQL injection prevention and syntax analysis
2. **Complexity limits**: resource-intensive queries are refused
3. **SELECT-only mode**: read-only database access for production safety
3. **SELECT-only mode**: Argos refuses anything but a read. The filter is a second net: the
database role is the boundary, so for a `select_only` database Argos asks the database
once per connection whether its role can write, and warns in `sql_test_connection`,
`sql_list_databases` and the pane when it can. Set `require_readonly_role=true` to refuse
such a connection instead
4. **Read-only pane**: what you run from the pane opens read-only at the database (SQLite
read-only mode, a read-only PostgreSQL or MySQL session) behind the SELECT-only check; SQL
Server has no session-level equivalent and relies on the check. The
Expand Down
2 changes: 2 additions & 0 deletions config.ini.template
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ select_only=true
timeout=30000
# Check column names against the cached schema before running a query (default: true)
# name_check=true
# Refuse to connect when the database role can write (default: false, which only warns)
# require_readonly_role=false

# Field Redaction Configuration (optional)
# redaction_enabled=true
Expand Down
8 changes: 8 additions & 0 deletions docs/api/mcp-tools-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -280,9 +280,17 @@ Test connectivity to a database, establish SSH tunnels if needed, and capture sc
Connection successful to production
SSH tunnel established
SELECT-only mode active
Database role: read-only (analytics_reader)
Schema captured: 45 tables, 1,247 columns
```

**A SELECT-only connection whose role can write:**
```
Connection successful to azure_sql
SELECT-only mode active
Warning: select_only is on, but this connection can write as dbo (db_owner). Argos's filter is the only guard. Connect as a read-only role.
```

**Failed Connection:**
```
Connection failed to production: Connection timeout after 30000ms
Expand Down
11 changes: 9 additions & 2 deletions docs/claude-code/pane.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,8 +123,15 @@ footer says `tab: leave field`, and Tab moves out so the hotkeys work again.
![The Connections tab: counts across the top and a card each for shop (SQLite, full access) and analytics (PostgreSQL, select-only)](../images/claude-code/connections.png)

One card per database from `config.ini`: type, host, whether it uses an SSH
tunnel or SSL, whether it is SELECT-only, and how old its captured schema is.
Passwords are never shown.
tunnel or SSL, whether it is SELECT-only, what its database role may do, and how
old its captured schema is. Passwords are never shown.

The `role` line comes from the MCP server, which checks a SELECT-only
connection's role each time it connects. `read-only` is what you want. `can
write: db_owner as dbo` (in the warning colour) means the role could change data
and Argos's SQL filter is the only thing in the way: connect as a read-only
role. `not checked yet` means the server has not connected to it since the
check shipped.

The single-key shortcuts are for the lists. While you type in the Schema filter
or the Editor field, the letters go into the field.
Expand Down
37 changes: 37 additions & 0 deletions docs/databases/postgresql.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,43 @@ ssl=true
select_only=true
```

### Azure Database for PostgreSQL with Azure CLI authentication

The Azure CLI's sign-in is the credential: Argos asks it for a Microsoft Entra
access token and sends that as the password, so no secret is written to
`config.ini`.

```ini
[database.azure_pg]
type=postgresql
host=myserver.postgres.database.azure.com
port=5432
database=myapp
username=argos-readers
authentication=azure-cli
select_only=true
# Only when the server's tenant is not the CLI's active context. Must be the GUID.
# azure_tenant_id=00000000-0000-0000-0000-000000000000
```

- `username` is the Entra principal's name as the database knows it: a user's
sign-in name, or a group's display name, as mapped with
`SELECT * FROM pgaadauth_create_principal('argos-readers', false, false);`.
Grant that role read access only.
- A token is valid for 5 to 60 minutes, so Argos fetches a fresh one for every
new connection the pool opens rather than holding one that expires.
- TLS with certificate verification is forced. `ssl=false` is a startup error,
and `ssl_verify=false` does not reach this path: an access token on an
unverified connection goes to whoever answers. Through an SSH tunnel the
certificate is checked against `host`, not the tunnel's local address, so a
private endpoint behind a bastion still verifies.
- `az login` must have been run. A token failure says so, rather than surfacing
as an opaque login error.
- `azure_config_dir=~/.azure-claude-ro` takes the token from that Azure CLI
profile instead of the server's, so the agent can use a reader identity signed
in with `AZURE_CONFIG_DIR=~/.azure-claude-ro az login` while your own shell
keeps your login.

### Cloud Database (Google Cloud SQL)
```ini
[database.gcp_sql]
Expand Down
30 changes: 28 additions & 2 deletions docs/databases/sql-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,8 +141,34 @@ Requirements:

- The [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) is installed and on `PATH`.
- `az login` has been run, and the signed-in identity has access to the database.
- The Azure AD identity is mapped to a database user, for example:
`CREATE USER [you@company.com] FROM EXTERNAL PROVIDER;`
- The Entra identity is mapped to a database user. Use a dedicated reader
identity or group with `db_datareader` only:
`CREATE USER [argos-readers] FROM EXTERNAL PROVIDER;` then
`ALTER ROLE db_datareader ADD MEMBER [argos-readers];`
- Not the server's Entra admin: the admin is a member of `db_owner` in every
user database and enters each one as `dbo`. Argos warns when a `select_only`
connection can write; see the
[database role check](../guides/security-guide.md#database-role-check).

### A separate Azure CLI profile

`az` keeps its sign-in in `~/.azure`, or in `AZURE_CONFIG_DIR` when that is set.
Start Argos with `AZURE_CONFIG_DIR` pointing at a profile where only the reader
identity is signed in (`AZURE_CONFIG_DIR=~/.azure-claude-ro az login`), or set
`azure_config_dir` on one database to give just that database its own profile:

```ini
[database.azure_cli]
type=mssql
host=myserver.database.windows.net
database=mydatabase
authentication=azure-cli
azure_config_dir=~/.azure-claude-ro
```

With `azure_config_dir` Argos runs `az account get-access-token` itself with that
profile, so two databases in one config can use two identities. The path must be
absolute; a leading `~` is your home directory.

### Choosing the tenant

Expand Down
7 changes: 7 additions & 0 deletions docs/guides/configuration-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,7 @@ value Argos cannot read is reported instead of guessed.
| `ssl` | `false` | Enable SSL/TLS | `true` |
| `timeout` | `30000` | Connection timeout (ms) | `15000` |
| `mcp_configurable` | `false` | Allow MCP tools to modify this database config | `true` |
| `require_readonly_role` | `false` | Refuse a `select_only` connection whose database role can write, or whose privileges could not be checked. Off, the check only warns; see [Database role check](security-guide.md#database-role-check) | `true` |
| `name_check` | `true` | Check column names against the cached schema before a SELECT runs; see [Name Checking](../api/mcp-tools-reference.md#name-checking) | `false` |

#### SQLite-Specific Parameters
Expand All @@ -128,11 +129,17 @@ value Argos cannot read is reported instead of guessed.
| `encrypt` | `true` | Enable connection encryption | `false` |
| `authentication` | `sql` | Authentication mode: `sql` or `azure-cli` | `azure-cli` |
| `azure_tenant_id` | *CLI's active tenant* | Tenant to take the Azure CLI token from (GUID) | `00000000-0000-0000-0000-000000000000` |
| `azure_config_dir` | *the server's profile* | Azure CLI profile directory (as `AZURE_CONFIG_DIR`) this database takes its token from, so it can use its own reader identity | `~/.azure-claude-ro` |

With `authentication=azure-cli` the connection uses the identity already signed
in to the Azure CLI, so `username` and `password` are neither required nor read.
See the [SQL Server guide](../databases/sql-server.md#azure-cli-authentication).

PostgreSQL takes `authentication=azure-cli` and `azure_tenant_id` too, for Azure
Database for PostgreSQL. There `username` is still required: it is the Entra
principal's name. See the
[PostgreSQL guide](../databases/postgresql.md#azure-database-for-postgresql-with-azure-cli-authentication).

### Default Port Numbers
- **PostgreSQL**: 5432
- **MySQL**: 3306
Expand Down
55 changes: 52 additions & 3 deletions docs/guides/security-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,13 @@ reaches the driver:
- **No dangerous construct appears** — `INTO OUTFILE`, `INTO DUMPFILE`,
`COPY … PROGRAM`, `WAITFOR DELAY`, and function calls such as `LOAD_FILE`,
`SYSTEM`, `SHELL`, `EXEC`, `BENCHMARK`, `SLEEP`, `pg_read_file`, `pg_ls_dir`,
`lo_import`, `lo_export`, `pg_sleep` and `dblink`. These are matched as
function calls with a word boundary, so an ordinary column named
`description` is not mistaken for `SCRIPT`.
`pg_sleep`, every `dblink*`, `lo_*` and `pg_file_*` function, and the
PostgreSQL functions that change state from inside a SELECT: `set_config`,
`pg_terminate_backend`, `pg_cancel_backend`, `pg_reload_conf`, `nextval` and
`setval`. These are matched as function calls with a word boundary, so an
ordinary column named `description` is not mistaken for `SCRIPT`.
- **No invisible formatting characters.** A zero-width space inside a keyword
hides the keyword from the scan, so none are accepted.
- **It is within the complexity limits** from `[security]`: joins, subqueries,
unions, group-bys, overall score and raw length.

Expand All @@ -50,6 +54,13 @@ complexity checks. It only stops restricting the leading command.

### The limits of it

The published bypass families (stacked statements, comments as whitespace,
`SET`, data-modifying CTEs, `SELECT ... INTO`, `COPY ... TO PROGRAM`, side-effect
functions, case and Unicode tricks) are pinned as a regression suite in
`tests/unit/security-bypass-regression.test.ts`. What no keyword list can see is
the inside of a function: a SELECT that calls a user-defined or extension
function that writes passes the filter.

This is defence in depth, not a substitute for database permissions. **Give the
account only the rights it needs.** If the account cannot write, no parser bug
can make it write:
Expand All @@ -69,6 +80,44 @@ CREATE USER 'argos_ro'@'%' IDENTIFIED BY '…';
GRANT SELECT ON app.* TO 'argos_ro'@'%';
```

### Database role check

Argos checks that boundary for you. Each time it connects to a `select_only`
database it asks the database, with read-only queries, what the role may do:

| Engine | What it reads | Counts as "can write" |
|--------|---------------|-----------------------|
| SQL Server | `USER_NAME()`, `IS_ROLEMEMBER` for `db_owner`, `db_datawriter`, `db_ddladmin`, `IS_SRVROLEMEMBER('sysadmin')` (NULL on Azure SQL Database), `HAS_PERMS_BY_NAME` on the database and every visible table | any of those roles, entering as `dbo`, or INSERT/UPDATE/DELETE/CREATE TABLE granted directly |
| PostgreSQL | `rolsuper`, membership of `pg_execute_server_program`, `pg_read_server_files`, `pg_write_server_files`, `pg_write_all_data`, `has_table_privilege` on every visible table, `has_schema_privilege(..., 'CREATE')`, `default_transaction_read_only` | superuser, any of those roles, INSERT/UPDATE/DELETE/TRUNCATE on a table, or CREATE in a schema |
| MySQL | `SHOW GRANTS FOR CURRENT_USER()` | anything beyond `SELECT`, `SHOW VIEW` and `USAGE`; `FILE` is named on its own |
| SQLite | the mode Argos opened the file in | a file opened read-write |

When the role can write, `sql_test_connection`, `sql_list_databases` and the
pane say so:

```
Warning: select_only is on, but this connection can write as dbo (db_owner).
Argos's filter is the only guard. Connect as a read-only role.
```

It is a warning, not a block. Set `require_readonly_role=true` on the database to
refuse the connection instead; with it on, a check that could not run also
refuses, because "unknown" is not "read-only".

Two results surprise people:

- **Azure SQL with `authentication=azure-cli`, signed in as the server's Entra
admin.** The admin is a member of `db_owner` in every user database and enters
each one as `dbo`. Sign in as a dedicated reader identity instead; see the
[SQL Server guide](../databases/sql-server.md#azure-cli-authentication).
- **PostgreSQL 14 and older.** Every role may create tables in `public` unless
that was revoked, so the check reports `CREATE in schema public`. Fix it with
`REVOKE CREATE ON SCHEMA public FROM PUBLIC;`.

MySQL roles granted to the user are listed in `SHOW GRANTS` by name only. The
check does not expand them, so a granted role counts as "can write": unknown is
not read-only. Grant `SELECT` to the user directly to get a clean result.

## Parameters

Pass values through `params` rather than building them into the SQL. Each
Expand Down
17 changes: 17 additions & 0 deletions plugin/hooks/lib/layout.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,23 @@ describe('the Connections tab', () => {
expect(text.match(/access\s+select-only/g)).toHaveLength(1)
})

it("says what a select-only connection's database role may do, and warns when it can write", () => {
const only = (c: ConnectionView) => model({ connections: { ask: 1, phase: 'done', answer: [c], failure: null } })
const rows = (c: ConnectionView) => paneRows(only(c), 100, 40)
const segment = (c: ConnectionView, text: RegExp) => rows(c).flatMap(r => r.segments).find(s => text.test(s.text))
// The fixture: the server found the SQLite file opened read-only.
expect(all(rows(CONNECTIONS[0]!))).toMatch(/role\s+read-only/)
const writer: ConnectionView = { ...CONNECTIONS[0]!, type: 'mssql', role: { checkedAt: 't', canWrite: true, principal: 'dbo', reasons: ['db_owner'] } }
expect(all(rows(writer))).toMatch(/role\s+can write: db_owner as dbo/)
expect(segment(writer, /^can write/)?.color).toBe('warning')
expect(all(rows({ ...writer, role: { ...writer.role!, canWrite: null } }))).toMatch(/role\s+could not be checked/)
expect(all(rows({ ...writer, role: null }))).toMatch(/role\s+not checked yet/)
// From a CLI older than the check.
const { role: _role, ...older } = writer
expect(all(rows(older))).toMatch(/role\s+not checked yet/)
expect(all(rows(CONNECTIONS[1]!))).toMatch(/role\s+not checked \(full access\)/)
})

it('says the engine, the host, the tunnel, MCP configuration and when the schema was captured', () => {
const captured = { ...CONNECTIONS[0]!, type: 'postgresql', host: 'db.internal', ssh: true, ssl: true, mcpConfigurable: true, schemaCapturedAt: '2000-01-01T00:00:00.000Z' }
const text = all(paneRows(model({ connections: { ask: 1, phase: 'done', answer: [captured], failure: null } }), 100, 40))
Expand Down
20 changes: 18 additions & 2 deletions plugin/hooks/lib/layout.ts
Original file line number Diff line number Diff line change
Expand Up @@ -126,10 +126,25 @@ function capturedOf(at: string | null, now: number): Segment[] {
return Number.isNaN(t) ? [{ text: 'never captured', dim: true }] : [{ text: `captured ${formatAge(now - t)} ago` }]
}

/**
* What the database role of a select_only connection may do, as the MCP server
* last found it. A role that can write is the warning: Argos's filter is then
* the only guard.
*/
function roleOf(c: ConnectionView): Segment[] {
if (!c.selectOnly) return [{ text: 'not checked (full access)', dim: true }]
const role = c.role ?? null
if (role === null) return [{ text: 'not checked yet', dim: true }]
if (role.canWrite === null) return [{ text: 'could not be checked', dim: true }]
const who: Segment[] = role.principal === null ? [] : [{ text: ` as ${role.principal}`, dim: true }]
if (!role.canWrite) return [{ text: 'read-only', color: STATUS_COLOURS.ok }, ...who]
return [{ text: `can write: ${role.reasons.join(', ')}`, color: STATUS_COLOURS.warn }, ...who]
}

/**
* One connection as a card: its name in the title, then its engine (a chip in
* its colour), host, tunnel, access, whether MCP may change its config, and
* when its schema was captured. The marked card is tinted, its first line
* its colour), host, tunnel, access, what its database role may do, whether
* MCP may change its config, and when its schema was captured. The marked card is tinted, its first line
* carrying the marker and the press that marks it.
*/
function connectionBlock(c: ConnectionView, i: number, marked: boolean, now: number): Block {
Expand All @@ -143,6 +158,7 @@ function connectionBlock(c: ConnectionView, i: number, marked: boolean, now: num
line('host', c.host === null ? [{ text: 'local', dim: true }] : [{ text: c.host }]),
line('tunnel', tunnel === '' ? [{ text: 'none', dim: true }] : [{ text: tunnel }]),
line('access', c.selectOnly ? [{ text: 'select-only', color: STATUS_COLOURS.ok }] : [{ text: 'full access', color: STATUS_COLOURS.warn }]),
line('role', roleOf(c)),
line('MCP', [{ text: `configurable: ${c.mcpConfigurable ? 'yes' : 'no'}`, ...(c.mcpConfigurable ? {} : { dim: true }) }]),
line('schema', capturedOf(c.schemaCapturedAt, now)),
]
Expand Down
Loading
Loading