asf-tooling commented on issue #1056:
URL:
https://github.com/apache/tooling-trusted-releases/issues/1056#issuecomment-4409872672
<!-- gofannon-issue-triage-bot v2 -->
**Automated triage** — analyzed at `main@2da7807a`
**Type:** `documentation` • **Classification:** `actionable` •
**Confidence:** `high`
**Application domain(s):** `web_api_infrastructure`,
`authentication_authorization`
### Summary
The issue reports that /api/docs and /api/openapi.json are publicly
accessible without authentication. The code already contains an explicit
audit_guidance comment in _app_setup_api_docs documenting that this is
intentional. The triage notes mark this as a duplicate of #182. @dave2wave's
comment confirms the decision to keep these public and requests follow-up to
formally document the rationale. The remaining action is adding proper security
documentation (beyond the inline code comment) explaining the policy decision.
### Where this lives in the code today
#### `atr/server.py` — `_app_setup_api_docs` (lines 210-250)
_currently does this_
This function sets up OpenAPI docs as intentionally public with an
audit_guidance comment explaining the rationale.
```python
def _app_setup_api_docs(app: base.QuartApp) -> None:
"""Configure OpenAPI documentation."""
import quart_schema
import atr.metadata as metadata
app.config["QUART_SCHEMA_SWAGGER_JS_URL"] =
"/static/js/min/swagger-ui-bundle.min.js"
app.config["QUART_SCHEMA_SWAGGER_CSS_URL"] =
"/static/css/swagger-ui.min.css"
quart_schema.QuartSchema(
app,
info=quart_schema.Info(
title="ATR API",
description="OpenAPI documentation for the Apache Trusted
Releases (ATR) platform.",
version=metadata.version,
),
openapi_provider_class=ApiOnlyOpenAPIProvider,
swagger_ui_path=None,
openapi_path="/api/openapi.json",
security_schemes={
"BearerAuth": quart_schema.HttpSecurityScheme(
scheme="bearer",
bearer_format="JWT",
)
},
)
# audit_guidance /api/docs and /api/openapi.json are intentionally
public: ATR exposes a public API
# and publishing its documentation is deliberate policy, consistent with
open-source ASF practice;
# admin routes are filtered from the spec by ApiOnlyOpenAPIProvider, so
no internal surface is exposed
@app.route("/api/docs")
@quart_schema.hide
async def swagger_ui() -> str:
return await template.render_string(
_SWAGGER_UI_TEMPLATE,
title="ATR API",
swagger_js_url=app.config["QUART_SCHEMA_SWAGGER_JS_URL"],
swagger_css_url=app.config["QUART_SCHEMA_SWAGGER_CSS_URL"],
swagger_init_url="/static/js/src/swagger-init.js",
openapi_url=quart.url_for("openapi"),
)
```
#### `atr/server.py` — `ApiOnlyOpenAPIProvider` (lines 127-131)
_currently does this_
This class filters the OpenAPI spec to only include /api routes, excluding
admin and internal routes from the public spec.
```python
class ApiOnlyOpenAPIProvider(quart_schema.OpenAPIProvider):
def generate_rules(self) -> Iterable[routing.Rule]:
for rule in super().generate_rules():
if rule.rule.startswith("/api"):
yield rule
```
### Where new code would go
- `docs/security/api-documentation-policy.md` — new file
Formal documentation of the decision to keep API docs public, as requested
by @dave2wave.
### Proposed approach
The team has already decided that /api/docs and /api/openapi.json should
remain public. The code already has an inline `audit_guidance` comment in
`_app_setup_api_docs` explaining the reasoning. @dave2wave requests this be
formally documented. The appropriate action is to create a security
documentation file that records: (1) the decision, (2) the rationale (ATR is
open-source, the API is public, admin routes are already filtered by
ApiOnlyOpenAPIProvider), (3) what mitigations are in place (admin route
filtering, no internal implementation details exposed), and (4) the ASVS
reference (13.4.5) this relates to.
Since this is marked as a duplicate of #182, the documentation may also
address that issue.
### Suggested patches
#### `docs/security/api-documentation-policy.md`
Create formal documentation of the decision to keep API docs public, as
requested by @dave2wave
````diff
--- /dev/null
+++ b/docs/security/api-documentation-policy.md
@@ -0,0 +1,32 @@
+# API Documentation Access Policy
+
+## Decision
+
+The OpenAPI specification (`/api/openapi.json`) and Swagger UI (`/api/docs`)
+are **intentionally public** and do not require authentication.
+
+## Rationale
+
+1. **ATR exposes a public API.** The API is designed to be consumed by
+ the `atr` CLI client, GitHub Actions, and other tooling. Publishing its
+ documentation publicly is consistent with this design.
+
+2. **Open-source practice.** As an Apache Software Foundation project, ATR
+ follows the principle that project documentation and interfaces should be
+ open and accessible.
+
+3. **No sensitive surface is exposed.** The `ApiOnlyOpenAPIProvider` class
+ (in `atr/server.py`) filters the specification to only include `/api`
+ routes. Admin routes, internal endpoints, and implementation details are
+ excluded from the public spec.
+
+4. **Authentication is enforced at endpoint level.** Individual API
endpoints
+ require JWT Bearer authentication (via `@jwtoken.require`). The OpenAPI
+ spec documents this requirement but does not bypass it.
+
+## ASVS Reference
+
+This decision addresses ASVS v5 §13.4.5 (L2). The control is satisfied by
+ensuring the public spec does not leak internal implementation details or
+admin-only functionality, while individual endpoints enforce their own
+authentication requirements.
````
### Open questions
- Is there a preferred location for security decision documentation (e.g.,
an existing docs/ directory structure or ADR format)?
- Should issue #182 (the duplicate) be closed along with this one once
documentation is added?
- Should the about.html link to /api/docs include any note about the API
requiring authentication for actual use?
### Files examined
- `atr/server.py`
- `atr/blueprints/api.py`
- `atr/blueprints/common.py`
- `atr/templates/about.html`
- `atr/blueprints/__init__.py`
- `atr/blueprints/get.py`
- `atr/blueprints/post.py`
- `atr/jwtoken.py`
---
*Draft from a triage agent. A human reviewer should validate before merging
any change. The agent did not run tests or verify diffs apply.*
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
