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

Align AOC tasks for Excititor and Concelier

Browse Source
This commit is contained in:
master
2025-10-31 18:50:15 +02:00
committed by root
parent 9e6d9fbae8
commit 8da4e12a90
334 changed files with 35528 additions and 34546 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/modules/notify/AGENTS.md
View File

@@ -1,22 +1,22 @@
# Notify agent guide
## Mission
Notify evaluates operator-defined rules against platform events and dispatches channel-specific payloads with full auditability.
## Key docs
- [Module README](./README.md)
- [Architecture](./architecture.md)
- [Implementation plan](./implementation_plan.md)
- [Task board](./TASKS.md)
## How to get started
1. Open ../../implplan/SPRINTS.md and locate the stories referencing this module.
2. Review ./TASKS.md for local follow-ups and confirm status transitions (TODO → DOING → DONE/BLOCKED).
3. Read the architecture and README for domain context before editing code or docs.
4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan.
## Guardrails
- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md).
- Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts.
- Keep Offline Kit parity in mind—document air-gapped workflows for any new feature.
# Notify agent guide
## Mission
Notify evaluates operator-defined rules against platform events and dispatches channel-specific payloads with full auditability.
## Key docs
- [Module README](./README.md)
- [Architecture](./architecture.md)
- [Implementation plan](./implementation_plan.md)
- [Task board](./TASKS.md)
## How to get started
1. Open ../../implplan/SPRINTS.md and locate the stories referencing this module.
2. Review ./TASKS.md for local follow-ups and confirm status transitions (TODO → DOING → DONE/BLOCKED).
3. Read the architecture and README for domain context before editing code or docs.
4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan.
## Guardrails
- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md).
- Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts.
- Keep Offline Kit parity in mind—document air-gapped workflows for any new feature.
- Update runbooks/observability assets when operational characteristics change.

70
docs/modules/notify/README.md
View File

@@ -1,35 +1,35 @@
# StellaOps Notify
Notify evaluates operator-defined rules against platform events and dispatches channel-specific payloads with full auditability.
## Responsibilities
- Process event streams and apply tenant-scoped routing rules.
- Render connector-specific payloads (email, Slack, Teams, webhook, custom).
- Enforce throttling, digests, and delivery retries.
- Surface delivery/audit data for UI and CLI consumers.
## Key components
- `StellaOps.Notify.WebService` (rules API + preview).
- `StellaOps.Notify.Worker` (delivery engine).
- Connector libraries under `StellaOps.Notify.Connectors.*`.
## Integrations & dependencies
- MongoDB for rule/channel storage.
- Redis/NATS for delivery queues.
- CLI/UI for authoring and monitoring notifications.
## Operational notes
- Schema fixtures in ./resources/schemas & ./resources/samples.
- Connector-specific monitoring dashboards.
- Offline runner guidance inside operations playbook.
## Related resources
- ./resources/schemas
- ./resources/samples
## Backlog references
- NOTIFY-SVC-38..40 (Notify backlog) referenced in `docs/README.md`.
- DOCS-NOTIFY updates tracked in ../../TASKS.md when available.
## Epic alignment
- **Epic 11 – Notifications Studio:** deliver notifications workspace, preview tooling, immutable delivery ledger, and tenant-scoped throttling/digest controls.
# StellaOps Notify
Notify evaluates operator-defined rules against platform events and dispatches channel-specific payloads with full auditability.
## Responsibilities
- Process event streams and apply tenant-scoped routing rules.
- Render connector-specific payloads (email, Slack, Teams, webhook, custom).
- Enforce throttling, digests, and delivery retries.
- Surface delivery/audit data for UI and CLI consumers.
## Key components
- `StellaOps.Notify.WebService` (rules API + preview).
- `StellaOps.Notify.Worker` (delivery engine).
- Connector libraries under `StellaOps.Notify.Connectors.*`.
## Integrations & dependencies
- MongoDB for rule/channel storage.
- Redis/NATS for delivery queues.
- CLI/UI for authoring and monitoring notifications.
## Operational notes
- Schema fixtures in ./resources/schemas & ./resources/samples.
- Connector-specific monitoring dashboards.
- Offline runner guidance inside operations playbook.
## Related resources
- ./resources/schemas
- ./resources/samples
## Backlog references
- NOTIFY-SVC-38..40 (Notify backlog) referenced in `docs/README.md`.
- DOCS-NOTIFY updates tracked in ../../TASKS.md when available.
## Epic alignment
- **Epic 11 – Notifications Studio:** deliver notifications workspace, preview tooling, immutable delivery ledger, and tenant-scoped throttling/digest controls.

18
docs/modules/notify/TASKS.md
View File

@@ -1,9 +1,9 @@
# Task board — Notify
> Local tasks should link back to ./AGENTS.md and mirror status updates into ../../TASKS.md when applicable.
| ID | Status | Owner(s) | Description | Notes |
|----|--------|----------|-------------|-------|
| NOTIFY-DOCS-0001 | DOING (2025-10-29) | Docs Guild | Validate that ./README.md aligns with the latest release notes. | See ./AGENTS.md |
| NOTIFY-OPS-0001 | TODO | Ops Guild | Review runbooks/observability assets after next sprint demo. | Sync outcomes back to ../../TASKS.md |
| NOTIFY-ENG-0001 | TODO | Module Team | Cross-check implementation plan milestones against ../../implplan/SPRINTS.md. | Update status via ./AGENTS.md workflow |
# Task board — Notify
> Local tasks should link back to ./AGENTS.md and mirror status updates into ../../TASKS.md when applicable.
| ID | Status | Owner(s) | Description | Notes |
|----|--------|----------|-------------|-------|
| NOTIFY-DOCS-0001 | DOING (2025-10-29) | Docs Guild | Validate that ./README.md aligns with the latest release notes. | See ./AGENTS.md |
| NOTIFY-OPS-0001 | TODO | Ops Guild | Review runbooks/observability assets after next sprint demo. | Sync outcomes back to ../../TASKS.md |
| NOTIFY-ENG-0001 | TODO | Module Team | Cross-check implementation plan milestones against ../../implplan/SPRINTS.md. | Update status via ./AGENTS.md workflow |

1030
docs/modules/notify/architecture.md
View File

File diff suppressed because it is too large Load Diff

122
docs/modules/notify/implementation_plan.md
View File

@@ -1,61 +1,61 @@
# Implementation plan — Notify
## Delivery phases
- **Phase 1 – Core rules engine & delivery ledger**
Implement rules/channels schema, event ingestion, rule evaluation, idempotent deliveries, and audit logging.
- **Phase 2 – Connectors & rendering**
Ship Slack/Teams/Email/Webhook connectors, template rendering, localization, throttling, retries, and secret referencing.
- **Phase 3 – Console & CLI authoring**
Provide UI/CLI for rule authoring, previews, channel health, delivery browsing, digests, and test sends.
- **Phase 4 – Governance & observability**
Add approvals, RBAC, tenant quotas, Notify metrics/logs/traces, dashboards, Notify-specific alerts, and Notify runbooks.
- **Phase 5 – Offline & compliance**
Produce Offline Kit bundles (rules/channels/deploy scripts), signed exports, retention policies, and auditing for regulated environments.
## Work breakdown
- **Service & worker**
- REST API for rules/channels/delivery history, idempotency middleware, digest scheduler.
- Worker pipelines for event intake, rule matching, template rendering, delivery execution, retries, and throttling.
- Delivery ledger capturing payload metadata, response, retry state, DSSE signatures.
- **Connectors**
- Slack/Teams/Email/Webhook plug-ins with configuration validation, rate limiting, error classification.
- Secrets referenced via Authority/Secret store; no plaintext storage.
- **Console & CLI**
- Console module for rules builder, condition editor, preview, test send, delivery insights, digests and schedule configuration.
- CLI (`stella notify rule|channel|delivery`) for automation, export/import.
- **Integrations**
- Event sources: Concelier, Excititor, Policy Engine, Vuln Explorer, Export Center, Attestor, Zastava, Scheduler.
- Notify events to Notify (meta) for failure escalations, accepted-risk expiration reminders.
- **Observability & ops**
- Metrics: delivery success/failure, retry counts, throttle hits, digest generation, channel health.
- Logs/traces with tenant, rule ID, channel, correlation ID; dashboards and alerts.
- Runbooks for misconfigured channels, throttling, event backlog, incident digest.
- **Docs & compliance**
- Update Notifications Studio guides, channel runbooks, security/RBAC docs, Offline Kit instructions.
- Provide compliance checklist (audit logging, retention, opt-out).
## Acceptance criteria
- Rules evaluate deterministically per event; deliveries idempotent with audit trail and DSSE signatures.
- Channel connectors support retries, rate limits, health checks, previews; secrets referenced securely.
- Console/CLI support rule creation, testing, digests, delivery browsing, and export/import workflows.
- Observability dashboards track delivery health; alerts fire for sustained failures or backlog; runbooks cover remediation.
- Offline Kit bundle contains configs, rules, digests, and deployment scripts for air-gapped installs.
- Notify respects tenancy and RBAC; governance (approvals, change log) enforced for high-impact rules.
## Risks & mitigations
- **Notification storms:** throttling, digests, dedupe windows, preview/test gating.
- **Secret compromise:** secret references only, rotation workflows, audit logging.
- **Connector API changes:** versioned adapter layer, nightly health checks, fallback channels.
- **Noise vs signal:** simulation previews, metrics, rule scoring, recommended defaults.
- **Offline parity:** export/import of rules, connectors, and digests with signed manifests.
## Test strategy
- **Unit:** rule evaluation, template rendering, connector clients, throttling, digests.
- **Integration:** end-to-end events from core services, multi-channel routing, retries, audit logging.
- **Performance:** burst throttling, digest creation, large rule sets.
- **Security:** RBAC tests, tenant isolation, secret reference validation, DSSE signature verification.
- **Offline:** export/import round-trips, Offline Kit deployment, manual delivery replay.
## Definition of done
- Notify service, workers, connectors, Console/CLI, observability, and Offline Kit assets shipped with documentation and runbooks.
- Compliance checklist appended to docs; ./TASKS.md and ../../TASKS.md updated with progress.
# Implementation plan — Notify
## Delivery phases
- **Phase 1 – Core rules engine & delivery ledger**
Implement rules/channels schema, event ingestion, rule evaluation, idempotent deliveries, and audit logging.
- **Phase 2 – Connectors & rendering**
Ship Slack/Teams/Email/Webhook connectors, template rendering, localization, throttling, retries, and secret referencing.
- **Phase 3 – Console & CLI authoring**
Provide UI/CLI for rule authoring, previews, channel health, delivery browsing, digests, and test sends.
- **Phase 4 – Governance & observability**
Add approvals, RBAC, tenant quotas, Notify metrics/logs/traces, dashboards, Notify-specific alerts, and Notify runbooks.
- **Phase 5 – Offline & compliance**
Produce Offline Kit bundles (rules/channels/deploy scripts), signed exports, retention policies, and auditing for regulated environments.
## Work breakdown
- **Service & worker**
- REST API for rules/channels/delivery history, idempotency middleware, digest scheduler.
- Worker pipelines for event intake, rule matching, template rendering, delivery execution, retries, and throttling.
- Delivery ledger capturing payload metadata, response, retry state, DSSE signatures.
- **Connectors**
- Slack/Teams/Email/Webhook plug-ins with configuration validation, rate limiting, error classification.
- Secrets referenced via Authority/Secret store; no plaintext storage.
- **Console & CLI**
- Console module for rules builder, condition editor, preview, test send, delivery insights, digests and schedule configuration.
- CLI (`stella notify rule|channel|delivery`) for automation, export/import.
- **Integrations**
- Event sources: Concelier, Excititor, Policy Engine, Vuln Explorer, Export Center, Attestor, Zastava, Scheduler.
- Notify events to Notify (meta) for failure escalations, accepted-risk expiration reminders.
- **Observability & ops**
- Metrics: delivery success/failure, retry counts, throttle hits, digest generation, channel health.
- Logs/traces with tenant, rule ID, channel, correlation ID; dashboards and alerts.
- Runbooks for misconfigured channels, throttling, event backlog, incident digest.
- **Docs & compliance**
- Update Notifications Studio guides, channel runbooks, security/RBAC docs, Offline Kit instructions.
- Provide compliance checklist (audit logging, retention, opt-out).
## Acceptance criteria
- Rules evaluate deterministically per event; deliveries idempotent with audit trail and DSSE signatures.
- Channel connectors support retries, rate limits, health checks, previews; secrets referenced securely.
- Console/CLI support rule creation, testing, digests, delivery browsing, and export/import workflows.
- Observability dashboards track delivery health; alerts fire for sustained failures or backlog; runbooks cover remediation.
- Offline Kit bundle contains configs, rules, digests, and deployment scripts for air-gapped installs.
- Notify respects tenancy and RBAC; governance (approvals, change log) enforced for high-impact rules.
## Risks & mitigations
- **Notification storms:** throttling, digests, dedupe windows, preview/test gating.
- **Secret compromise:** secret references only, rotation workflows, audit logging.
- **Connector API changes:** versioned adapter layer, nightly health checks, fallback channels.
- **Noise vs signal:** simulation previews, metrics, rule scoring, recommended defaults.
- **Offline parity:** export/import of rules, connectors, and digests with signed manifests.
## Test strategy
- **Unit:** rule evaluation, template rendering, connector clients, throttling, digests.
- **Integration:** end-to-end events from core services, multi-channel routing, retries, audit logging.
- **Performance:** burst throttling, digest creation, large rule sets.
- **Security:** RBAC tests, tenant isolation, secret reference validation, DSSE signature verification.
- **Offline:** export/import round-trips, Offline Kit deployment, manual delivery replay.
## Definition of done
- Notify service, workers, connectors, Console/CLI, observability, and Offline Kit assets shipped with documentation and runbooks.
- Compliance checklist appended to docs; ./TASKS.md and ../../TASKS.md updated with progress.