docs: rewrite README and docs for the full-access design, generate tool inventory
This commit is contained in:
Latte committed
1 parent
68bd8700dc
commit
7c7cfc05ff
13 files changed
+1693
-1026
No files matched your search
+34
-106
@@ -1,119 +1,47 @@
|
||||
# Raw API Dispatch (`gitea_request`)
|
||||
# Raw API tool: `gitea_api_request`
|
||||
|
||||
`gitea_request` is a generic escape hatch that can call **any** Gitea REST
|
||||
endpoint by method and path. It exists for the long tail of the Gitea API that
|
||||
the curated, typed tools do not cover (merging PRs, reviews, writing files,
|
||||
webhooks, branch/tag protections, collaborators, Actions/CI, packages,
|
||||
notifications, and so on).
|
||||
`gitea_api_request` sends one request to any Gitea API endpoint. It exists for endpoints that are
|
||||
newer than the pinned Gitea 28.1.0 swagger, so a Gitea upgrade does not have to wait for a
|
||||
catalog update. Prefer the generated tools whenever one exists: they have typed arguments, hints
|
||||
and validation.
|
||||
|
||||
> Prefer the dedicated tools whenever one exists. Use `gitea_request` only for
|
||||
> endpoints they do not cover. It is subject to policy, write-mode, and the
|
||||
> sensitive-path denylist described below.
|
||||
It is a hand-written tool, not part of the generated catalog, and belongs to the `misc` domain.
|
||||
It is annotated as not read-only and destructive.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Field | Type | Notes |
|
||||
|-------|------|-------|
|
||||
| `method` | enum | `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` (case-insensitive). Any other method is rejected before any network call. |
|
||||
| `path` | string | Gitea REST path. The `/api/v1` prefix is optional. A full URL may be supplied — the host and query string are stripped. |
|
||||
| `query` | object | Optional query-string parameters. |
|
||||
| `body` | object | Optional JSON request body. **Never logged.** |
|
||||
| Argument | Type | Rules |
|
||||
|---|---|---|
|
||||
| `method` | string | `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. Required. |
|
||||
| `path` | string | Required. Starts with `/`, relative to `/api/v1`, at most 2048 characters. |
|
||||
| `query` | object | Optional. Values are strings, numbers, booleans or arrays of them. |
|
||||
| `body` | any JSON | Optional request body. |
|
||||
| `sudo` | string | Optional Gitea login to act as (site-admin tokens only), as for every tool. |
|
||||
|
||||
The response is returned in a stable envelope:
|
||||
Unknown arguments are rejected. The path is checked: no empty, `.` or `..` segments, and no
|
||||
backslash, `?`, `#`, `%` or control characters (put parameters in `query`). A body is never
|
||||
logged or returned. The `token`, `access_token` and `sudo` query parameters are refused,
|
||||
because credentials belong in the identity, not in the URL.
|
||||
|
||||
## Behaviour
|
||||
|
||||
- It goes through the same executor as every generated tool: the identity's token, no redirects,
|
||||
response limits, redaction and secret masking, the result envelope and one audit event.
|
||||
- There is no allow list of paths and no write classification: with full access, the token's
|
||||
scopes and the identity's Gitea permissions are the limit.
|
||||
- `READ_ONLY=true` keeps the tool listed but it accepts only `GET`.
|
||||
- `TOOLSETS` without `misc`, or `DISABLED_TOOLS=gitea_api_request`, removes it.
|
||||
- The audit event records the method and the path, so it is visible which endpoint was called.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
{
|
||||
"method": "GET",
|
||||
"path": "/api/v1/repos/acme/app/pulls/1",
|
||||
"write": false,
|
||||
"repository": "acme/app",
|
||||
"data": { "...": "..." }
|
||||
"path": "/repos/acme/app/issues",
|
||||
"query": {"state": "open", "limit": 10}
|
||||
}
|
||||
```
|
||||
|
||||
List responses add `count` and `omitted`; oversized objects are returned as a
|
||||
truncated JSON string with `"truncated": true`. All responses are bounded by
|
||||
`MAX_TOOL_RESPONSE_ITEMS` / `MAX_TOOL_RESPONSE_CHARS`.
|
||||
|
||||
## Two-layer authorization
|
||||
|
||||
A single tool surface would normally collapse the granularity of `policy.yaml`.
|
||||
To preserve it, every call is authorized twice:
|
||||
|
||||
1. **Central gate (`server.py`).** The registered `gitea_request` tool name is
|
||||
allowed/denied like any other tool. In service-PAT mode the central gate also
|
||||
parses the target repository from the path and verifies that the signed-in
|
||||
user has permission on that repository before the service PAT is used.
|
||||
2. **Handler gate (`raw_tools.py`).** The handler derives a coarse **virtual
|
||||
tool name** of the form `gitea_request:<METHOD>:<top-path-segment>` (for
|
||||
example `gitea_request:GET:repos` or `gitea_request:DELETE:repos`) and runs
|
||||
it back through the policy engine with the parsed repository, target path, and
|
||||
a `is_write` flag (`true` for any method other than GET/HEAD). This reuses the
|
||||
existing write-mode + write-whitelist enforcement and lets `policy.yaml` allow
|
||||
or deny raw dispatch per method and per top-level path segment.
|
||||
|
||||
Because the policy engine matches tool names by **exact set membership** (only
|
||||
`paths` use globbing), the virtual name is deliberately coarse and stable.
|
||||
|
||||
### Example: lock raw dispatch to reads
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
deny:
|
||||
- gitea_request:POST:repos
|
||||
- gitea_request:PUT:repos
|
||||
- gitea_request:PATCH:repos
|
||||
- gitea_request:DELETE:repos
|
||||
```
|
||||
|
||||
## Sensitive-path denylist
|
||||
|
||||
Independently of `policy.yaml`, the handler blocks endpoints that touch an
|
||||
admin or credential surface **for every method, including GET** (a GET on these
|
||||
already leaks credentials or privileged configuration):
|
||||
|
||||
- `/admin`
|
||||
- `*tokens*`
|
||||
- `*secrets*`
|
||||
- `*hooks*`
|
||||
- `*keys*` (and `*gpg_keys*`)
|
||||
- `applications/oauth2`
|
||||
- `actions/runners/registration-token`
|
||||
|
||||
This denylist lives in the handler and **cannot be re-opened from
|
||||
`policy.yaml`.** It is overridden only by setting `RAW_API_ALLOW_SENSITIVE=true`.
|
||||
|
||||
## Configuration
|
||||
|
||||
| Variable | Default | Notes |
|
||||
|----------|---------|-------|
|
||||
| `RAW_API_ENABLED` | `true` | Killswitch. When `false`, `gitea_request` refuses every dispatch with a `403`. |
|
||||
| `RAW_API_ALLOW_SENSITIVE` | `false` | When `true`, the admin/credential denylist is bypassed. Leave `false` unless you fully understand the exposure. |
|
||||
|
||||
## Security warning
|
||||
|
||||
> With `WRITE_MODE=true`, the **write whitelist is the only brake** on
|
||||
> `POST`/`PUT`/`PATCH`/`DELETE` across the *entire* Gitea API surface reachable
|
||||
> by `gitea_request`. Any write method against a whitelisted repository will be
|
||||
> attempted. Keep the whitelist tight, prefer denying the write virtual tool
|
||||
> names in `policy.yaml`, and keep `RAW_API_ALLOW_SENSITIVE=false`.
|
||||
|
||||
## Behavioral notes and edge cases
|
||||
|
||||
- **Full URL supplied instead of a path:** only the path is used; the host and
|
||||
query string are discarded (`query` carries query parameters).
|
||||
- **Path traversal (`..`):** rejected during argument validation (`400`).
|
||||
- **Unknown / non-HTTP method:** rejected during argument validation, before any
|
||||
network call.
|
||||
- **Cross-repo endpoints** such as `/repos/search` and `/repos/issues/search`
|
||||
are intentionally *not* treated as repository-scoped, so `repository` is
|
||||
`null` for them.
|
||||
- **Non-repository writes** such as `POST /user/repos` or `POST /orgs` are denied
|
||||
with *"write operation requires a repository target"*. This is the secure
|
||||
default — the per-user permission model is repository-scoped, so there is no
|
||||
repository against which to verify the write. This behavior is intentional and
|
||||
is not worked around.
|
||||
- **Service-PAT mode:** non-repository endpoints (for example `GET /user/orgs`)
|
||||
are denied by the central gate because per-user permission can only be verified
|
||||
against a repository target. Use the dedicated tools for those, or run in
|
||||
OAuth-only mode.
|
||||
The result is the usual envelope, with `request.path` set to the path that was called and the
|
||||
response under `data`. Content under `data` is untrusted, as everywhere.
|
||||
Reference in new issue
Block a user