stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity

feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules

Browse Source 
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes.
- Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes.
- Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables.
- Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
This commit is contained in:
master
2025-10-30 00:09:39 +02:00
parent 3154c67978
commit 7b5bdcf4d3
503 changed files with 16136 additions and 54638 deletions
Download Patch File Download Diff File Expand all files Collapse all files

348
docs/ui/admin.md
View File

@@ -1,174 +1,174 @@
# StellaOps Console - Admin Workspace
> **Audience:** Authority Guild, Console admins, support engineers, tenant operators.
> **Scope:** Tenant management, role mapping, token lifecycle, integrations, fresh-auth prompts, security guardrails, offline behaviour, and compliance checklist for Sprint 23.
The Admin workspace centralises Authority-facing controls: tenants, roles, API clients, tokens, and integrations. It surfaces RBAC mappings, token issuance logs, and bootstrap flows with the same offline-first guarantees as the rest of the console.
---
## 1. Access and prerequisites
- **Route:** `/console/admin` with sub-routes for tenants, users, roles, tokens, integrations, audit, and bootstrap.
- **Scopes:**
- `ui.admin` (base access)
- `authority:tenants.read` / `authority:tenants.write`
- `authority:roles.read` / `authority:roles.write`
- `authority:tokens.read` / `authority:tokens.revoke`
- `authority:clients.read` / `authority:clients.write`
- `authority:audit.read` (view audit trails)
- **Fresh-auth:** Sensitive actions (token revoke, bootstrap key issue, signing key rotation) require fresh-auth challenge.
- **Dependencies:** Authority service (`/internal/*` APIs), revocation export, JWKS, licensing posture endpoint, integration config store.
---
## 2. Layout overview
```
+--------------------------------------------------------------------+
| Header: Tenant picker - environment badge - security banner |
+--------------------------------------------------------------------+
| Tabs: Tenants | Roles & Scopes | Users & Tokens | Integrations | Audit |
+--------------------------------------------------------------------+
| Sidebar: Quick actions (Invite user, Create client, Export revocations)
| Main panel varies per tab |
+--------------------------------------------------------------------+
```
The header includes offline status indicator and link to Authority health page.
---
## 3. Tenants tab
| Field | Description |
|-------|-------------|
| **Tenant ID** | Lowercase slug used in tokens and client registrations. |
| **Display name** | Human-friendly name. |
| **Status** | `active`, `suspended`, `pending`. Suspended tenants block token issuance. |
| **Isolation mode** | `dedicated`, `shared`, or `sandbox`. Drives RBAC defaults. |
| **Default roles** | Roles automatically assigned to new users within the tenant. |
| **Offline snapshots** | Latest snapshot timestamp, checksum, operator. |
Actions:
- `Create tenant` (requires `authority:tenants.write`). Form captures display name, slug, isolation mode, default roles, bootstrap contact, optional plan metadata.
- `Suspend/Resume` toggles token issuance and surfaces audit entry.
- `Export tenant bundle` downloads tenant-specific revocation + JWKS package for air-gap distribution.
- CLI parity: `stella auth tenant create --tenant <id>`, `stella auth tenant suspend --tenant <id>`.
---
## 4. Roles & scopes tab
- Table lists roles with mapped scopes and audiences.
- Inline editor supports adding/removing scopes (with validation).
- Scope categories: UI, Scanner, Concelier, Excititor, Policy, Attestor, Notifier, Scheduler, Offline kit.
- Visual diff shows impact of changes on linked clients/users before committing.
- "Effective permissions" view summarises what each role grants per service.
- CLI parity: `stella auth role update --role ui.admin --add-scope authority:tokens.revoke`.
---
## 5. Users & tokens tab
Sections:
1. **User list** - identity, tenant, roles, last login, MFA status. Actions include reset password (if plugin supports), enforce fresh-auth, disable user.
2. **Token inventory** - lists active tokens (access/refresh/device). Columns: token ID, type, subject, audience, issued at, expires, status. Toggle to show revoked tokens.
3. **Token details** drawer shows claims, sender constraint (`cnf`), issuance metadata, revocation history.
4. **Revoke token** action requires fresh-auth and prompts for reason (incident, user request, compromise).
5. **Bulk revoke** (per tenant or role) triggers Authority revocation export to ensure downstream services purge caches.
Audit entries appear for every user/token change. CLI parity: `stella auth token revoke --token <id>`.
---
## 6. Integrations tab
- **Authority clients** list (service accounts) with grant types, allowed scopes, DPoP/mTLS settings, tenant hints, and rotation status.
- **Bootstrap bundles** - downloadable templates for new clients/users; includes configuration YAML and CLI instructions.
- **External IdP connectors** (optional) - displays status for SAML/OIDC plugins; includes metadata upload field and test login result.
- **Licensing posture** - read-only panel summarising plan tier, entitlement expiry, and contact info (pulled from licensing service).
- **Notifications** - optional webhook configuration for token events (on revoke, on failure).
- CLI parity: `stella auth client create --client concelier --grant client_credentials --tenant prod`.
---
## 7. Audit tab
- Timeline view of administrative events (user changes, role updates, token revocations, bootstrap actions, key rotations).
- Filters: event type, actor, tenant, scope, correlation ID.
- Export button downloads CSV/JSON for SOC ingestion.
- "Open in logs" copies search query pre-populated with correlation IDs.
- CLI parity: `stella auth audit export --from 2025-10-20`.
---
## 8. Fresh-auth prompts
- High-risk actions (revoke all tokens, rotate signing key, create privileged client) trigger modal requiring credential re-entry or hardware key touch.
- Fresh-auth window is 5 minutes; countdown displayed.
- UI surface indicates when current session is outside fresh-auth window; sensitive buttons disabled until re-auth.
- Audit log records fresh-auth events (`authority.fresh_auth.start`, `authority.fresh_auth.success`).
- CLI parity: `stella auth fresh-auth` obtains short-lived token for scriptable flows.
---
## 9. Security guardrails
- DPoP enforcement reminders for UI clients; console warns if any client lacks sender constraint.
- mTLS enforcement summary for high-value audiences (Signer/Attestor).
- Token policy checklists (access token TTL, refresh token policy) with alerts when deviating from defaults.
- Revocation bundle export status (timestamp, digest, operator).
- Key rotation panel showing current `kid`, last rotation, next scheduled rotation, and manual trigger button (ties into Authority rotate API).
- CLI parity: `stella auth signing rotate` for script automation.
---
## 10. Offline and air-gap behaviour
- Offline banner indicates snapshot version; disables direct remote calls.
- Tenant/role edits queue change manifests; UI instructs users to apply via CLI (`stella auth apply --bundle <file>`).
- Token inventory shows snapshot state; revoke buttons generate scripts for offline Authority host.
- Integrations tab offers manual download/upload for client definitions and IdP metadata.
- Audit exports default to local storage with checksum output for transfer.
---
## 11. Screenshot coordination
- Placeholders:
- `![Admin tenants placeholder](../assets/ui/admin/tenants-placeholder.png)`
- `![Admin roles placeholder](../assets/ui/admin/roles-placeholder.png)`
- `![Admin tokens placeholder](../assets/ui/admin/tokens-placeholder.png)`
- Capture real screenshots with Authority Guild once Sprint 23 UI is final (tracked in `#console-screenshots`, 2025-10-26 entry). Provide both light and dark theme variants.
---
## 12. References
- `/docs/ARCHITECTURE_AUTHORITY.md` - Authority architecture.
- `/docs/11_AUTHORITY.md` - Authority service overview.
- `/docs/security/authority-scopes.md` - scope definitions.
- `/docs/ui/policies.md` - policy approvals requiring fresh-auth.
- `/docs/ui/console-overview.md` - navigation shell.
- `/docs/cli/authentication.md` (pending) and `/docs/cli/policy.md` for CLI flows.
- `/docs/ops/scheduler-runbook.md` for integration with scheduler token rotation.
---
## 13. Compliance checklist
- [ ] Tenants, roles/scopes, and token management documented with actions and CLI parity.
- [ ] Integrations and audit views covered.
- [ ] Fresh-auth prompts and guardrails described.
- [ ] Security controls (DPoP, mTLS, key rotation, revocations) captured.
- [ ] Offline behaviour explained with script guidance.
- [ ] Screenshot placeholders and coordination noted.
- [ ] References validated.
---
*Last updated: 2025-10-26 (Sprint 23).*
# StellaOps Console - Admin Workspace
> **Audience:** Authority Guild, Console admins, support engineers, tenant operators.
> **Scope:** Tenant management, role mapping, token lifecycle, integrations, fresh-auth prompts, security guardrails, offline behaviour, and compliance checklist for Sprint 23.
The Admin workspace centralises Authority-facing controls: tenants, roles, API clients, tokens, and integrations. It surfaces RBAC mappings, token issuance logs, and bootstrap flows with the same offline-first guarantees as the rest of the console.
---
## 1. Access and prerequisites
- **Route:** `/console/admin` with sub-routes for tenants, users, roles, tokens, integrations, audit, and bootstrap.
- **Scopes:**
- `ui.admin` (base access)
- `authority:tenants.read` / `authority:tenants.write`
- `authority:roles.read` / `authority:roles.write`
- `authority:tokens.read` / `authority:tokens.revoke`
- `authority:clients.read` / `authority:clients.write`
- `authority:audit.read` (view audit trails)
- **Fresh-auth:** Sensitive actions (token revoke, bootstrap key issue, signing key rotation) require fresh-auth challenge.
- **Dependencies:** Authority service (`/internal/*` APIs), revocation export, JWKS, licensing posture endpoint, integration config store.
---
## 2. Layout overview
```
+--------------------------------------------------------------------+
| Header: Tenant picker - environment badge - security banner |
+--------------------------------------------------------------------+
| Tabs: Tenants | Roles & Scopes | Users & Tokens | Integrations | Audit |
+--------------------------------------------------------------------+
| Sidebar: Quick actions (Invite user, Create client, Export revocations)
| Main panel varies per tab |
+--------------------------------------------------------------------+
```
The header includes offline status indicator and link to Authority health page.
---
## 3. Tenants tab
| Field | Description |
|-------|-------------|
| **Tenant ID** | Lowercase slug used in tokens and client registrations. |
| **Display name** | Human-friendly name. |
| **Status** | `active`, `suspended`, `pending`. Suspended tenants block token issuance. |
| **Isolation mode** | `dedicated`, `shared`, or `sandbox`. Drives RBAC defaults. |
| **Default roles** | Roles automatically assigned to new users within the tenant. |
| **Offline snapshots** | Latest snapshot timestamp, checksum, operator. |
Actions:
- `Create tenant` (requires `authority:tenants.write`). Form captures display name, slug, isolation mode, default roles, bootstrap contact, optional plan metadata.
- `Suspend/Resume` toggles token issuance and surfaces audit entry.
- `Export tenant bundle` downloads tenant-specific revocation + JWKS package for air-gap distribution.
- CLI parity: `stella auth tenant create --tenant <id>`, `stella auth tenant suspend --tenant <id>`.
---
## 4. Roles & scopes tab
- Table lists roles with mapped scopes and audiences.
- Inline editor supports adding/removing scopes (with validation).
- Scope categories: UI, Scanner, Concelier, Excititor, Policy, Attestor, Notifier, Scheduler, Offline kit.
- Visual diff shows impact of changes on linked clients/users before committing.
- "Effective permissions" view summarises what each role grants per service.
- CLI parity: `stella auth role update --role ui.admin --add-scope authority:tokens.revoke`.
---
## 5. Users & tokens tab
Sections:
1. **User list** - identity, tenant, roles, last login, MFA status. Actions include reset password (if plugin supports), enforce fresh-auth, disable user.
2. **Token inventory** - lists active tokens (access/refresh/device). Columns: token ID, type, subject, audience, issued at, expires, status. Toggle to show revoked tokens.
3. **Token details** drawer shows claims, sender constraint (`cnf`), issuance metadata, revocation history.
4. **Revoke token** action requires fresh-auth and prompts for reason (incident, user request, compromise).
5. **Bulk revoke** (per tenant or role) triggers Authority revocation export to ensure downstream services purge caches.
Audit entries appear for every user/token change. CLI parity: `stella auth token revoke --token <id>`.
---
## 6. Integrations tab
- **Authority clients** list (service accounts) with grant types, allowed scopes, DPoP/mTLS settings, tenant hints, and rotation status.
- **Bootstrap bundles** - downloadable templates for new clients/users; includes configuration YAML and CLI instructions.
- **External IdP connectors** (optional) - displays status for SAML/OIDC plugins; includes metadata upload field and test login result.
- **Licensing posture** - read-only panel summarising plan tier, entitlement expiry, and contact info (pulled from licensing service).
- **Notifications** - optional webhook configuration for token events (on revoke, on failure).
- CLI parity: `stella auth client create --client concelier --grant client_credentials --tenant prod`.
---
## 7. Audit tab
- Timeline view of administrative events (user changes, role updates, token revocations, bootstrap actions, key rotations).
- Filters: event type, actor, tenant, scope, correlation ID.
- Export button downloads CSV/JSON for SOC ingestion.
- "Open in logs" copies search query pre-populated with correlation IDs.
- CLI parity: `stella auth audit export --from 2025-10-20`.
---
## 8. Fresh-auth prompts
- High-risk actions (revoke all tokens, rotate signing key, create privileged client) trigger modal requiring credential re-entry or hardware key touch.
- Fresh-auth window is 5 minutes; countdown displayed.
- UI surface indicates when current session is outside fresh-auth window; sensitive buttons disabled until re-auth.
- Audit log records fresh-auth events (`authority.fresh_auth.start`, `authority.fresh_auth.success`).
- CLI parity: `stella auth fresh-auth` obtains short-lived token for scriptable flows.
---
## 9. Security guardrails
- DPoP enforcement reminders for UI clients; console warns if any client lacks sender constraint.
- mTLS enforcement summary for high-value audiences (Signer/Attestor).
- Token policy checklists (access token TTL, refresh token policy) with alerts when deviating from defaults.
- Revocation bundle export status (timestamp, digest, operator).
- Key rotation panel showing current `kid`, last rotation, next scheduled rotation, and manual trigger button (ties into Authority rotate API).
- CLI parity: `stella auth signing rotate` for script automation.
---
## 10. Offline and air-gap behaviour
- Offline banner indicates snapshot version; disables direct remote calls.
- Tenant/role edits queue change manifests; UI instructs users to apply via CLI (`stella auth apply --bundle <file>`).
- Token inventory shows snapshot state; revoke buttons generate scripts for offline Authority host.
- Integrations tab offers manual download/upload for client definitions and IdP metadata.
- Audit exports default to local storage with checksum output for transfer.
---
## 11. Screenshot coordination
- Placeholders:
- `![Admin tenants placeholder](../assets/ui/admin/tenants-placeholder.png)`
- `![Admin roles placeholder](../assets/ui/admin/roles-placeholder.png)`
- `![Admin tokens placeholder](../assets/ui/admin/tokens-placeholder.png)`
- Capture real screenshots with Authority Guild once Sprint 23 UI is final (tracked in `#console-screenshots`, 2025-10-26 entry). Provide both light and dark theme variants.
---
## 12. References
- `/docs/modules/authority/architecture.md` - Authority architecture.
- `/docs/11_AUTHORITY.md` - Authority service overview.
- `/docs/security/authority-scopes.md` - scope definitions.
- `/docs/ui/policies.md` - policy approvals requiring fresh-auth.
- `/docs/ui/console-overview.md` - navigation shell.
- `/docs/modules/cli/guides/authentication.md` (pending) and `/docs/modules/cli/guides/policy.md` for CLI flows.
- `/docs/modules/scheduler/operations/worker.md` for integration with scheduler token rotation.
---
## 13. Compliance checklist
- [ ] Tenants, roles/scopes, and token management documented with actions and CLI parity.
- [ ] Integrations and audit views covered.
- [ ] Fresh-auth prompts and guardrails described.
- [ ] Security controls (DPoP, mTLS, key rotation, revocations) captured.
- [ ] Offline behaviour explained with script guidance.
- [ ] Screenshot placeholders and coordination noted.
- [ ] References validated.
---
*Last updated: 2025-10-26 (Sprint 23).*