Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
A first run that ends at a login nobody can perform (#809)
Beenu Arora925ded26d65a
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 66e796b2a..9a81bac37 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -358,6 +358,16 @@ jobs:run: |python3 -m pip install --quiet pytestpython3 -m pytest tests/test_support_bundle.py -q+ # A clean install has to end with an account somebody can sign into.+ # It did not: `make up` and `make smoke` both passed and login was+ # impossible, because the seeded address was a reserved domain the+ # login route rejects with a 422, its password hash matched nothing+ # documented, and the published console image was a demo build. Every+ # one of those lived between two files that never mention each other.+ - name: First-run credentials and image tags+ run: |+ python3 -m pip install --quiet pytest pyyaml email-validator+ python3 -m pytest tests/test_first_run_gate.py -q# Phase 8 — a production prompt cannot change without a version bump +# lock regeneration (the signal that must trigger an eval re-grade).- name: Verify prompt lock is current (Phase 8)diff --git a/.github/workflows/golden-pipeline.yml b/.github/workflows/golden-pipeline.ymlindex 65cbf4500..e780a7a97 100644--- a/.github/workflows/golden-pipeline.yml+++ b/.github/workflows/golden-pipeline.yml@@ -84,6 +84,53 @@ jobs:- name: make doctor reports a healthy stackrun: ./scripts/doctor.sh+ # The quick start ends at a login form, and for a long time that is+ # where it ended: `make up` and `make smoke` both passed and no account+ # existed that could sign in. A pipeline test cannot catch that, because+ # nothing in the pipeline authenticates. So the documented command runs+ # here and the credential it prints is used against the real route — the+ # same two steps a new user performs, in the same order.+ - name: make bootstrap creates an administrator that can log in+ run: |+ set -euo pipefail+ out="$(docker compose run --rm -T api python -m app.scripts.bootstrap_admin)"+ echo "$out" | sed 's/^\( Password \).*/\1<redacted>/'++ email="$(printf '%s' "$out" | awk '/^ Email/ {print $2}')"+ password="$(printf '%s' "$out" | awk '/^ Password/ {print $2}')"+ if [ -z "$email" ] || [ -z "$password" ]; then+ echo "::error::bootstrap printed no credential a user could copy"+ exit 1+ fi++ code="$(curl -s -o /tmp/login.json -w '%{http_code}' \+ -X POST http://localhost:8000/api/v1/auth/login \+ -H 'Content-Type: application/json' \+ --data "$(python3 -c 'import json,sys; print(json.dumps({"email":sys.argv[1],"password":sys.argv[2]}))' "$email" "$password")")"++ if [ "$code" != "200" ]; then+ # 422 is the original defect: the address was rejected before the+ # password was ever compared. Name it so the next reader does not+ # have to rediscover that it is not a wrong-password failure.+ echo "::error::login returned $code for the credential bootstrap just printed"+ jq . /tmp/login.json || cat /tmp/login.json+ exit 1+ fi+ jq -e '.access_token | length > 0' /tmp/login.json >/dev/null+ echo "logged in as $email with the password the tool printed"++ # Re-running must not hand out a password that does not work. `make up`+ # calls bootstrap unconditionally, so this runs on every start.+ - name: bootstrap is idempotent+ run: |+ set -euo pipefail+ out="$(docker compose run --rm -T api python -m app.scripts.bootstrap_admin)"+ echo "$out"+ printf '%s' "$out" | grep -q 'already exists' || {+ echo "::error::a second bootstrap did not report the existing administrator"+ exit 1+ }+- name: Golden pipeline — one real event end to endrun: python3 tests/e2e/golden_pipeline/run_golden_pipeline.pydiff --git a/.github/workflows/publish-images.yml b/.github/workflows/publish-images.ymlindex 1a1eaa72e..a6f62ad65 100644--- a/.github/workflows/publish-images.yml+++ b/.github/workflows/publish-images.yml@@ -56,6 +56,25 @@ jobs:dockerfile: apps/web/Dockerfileimage: ghcr.io/beenuar/aisoc-web+ # The demo build of the console, published under its own `demo` tag.+ #+ # It used to be the *only* build: `latest` carried the demo bundle,+ # and `latest` is what `docker-compose.yml` pulls for `make up`. Next+ # inlines NEXT_PUBLIC_* at build time, so a self-hoster had no runtime+ # escape — their console announced "Demo data resets daily at 00:00+ # UTC. All write actions are disabled." over their own real alerts,+ # disabled every write control, and offered a "Self-host AiSOC" link+ # inside an already self-hosted install.+ #+ # Splitting the tag means nobody has to choose between a working demo+ # and a usable self-host image. `latest` is the product;+ # `infra/compose/docker-compose.demo.yml` pulls `demo`.+ - service: web-demo+ context: .+ dockerfile: apps/web/Dockerfile+ image: ghcr.io/beenuar/aisoc-web+ demo: 'true'+# Full-stack backend images. Published so `docker compose up -d` can# pull instead of build (with `pull_policy: missing`), shaving the# cold-start time from ~15 min to ~90 s on a fresh clone.@@ -114,21 +133,26 @@ jobs:uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6with:images: ${{ matrix.image }}+ # The demo build shares the repository but never the moving tags a+ # self-hoster pulls. `latest` and `main` are the product.tags: |- type=raw,value=main,enable=${{ github.ref == 'refs/heads/main' }}- type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}- type=sha,prefix=sha-,format=short-- # Web image needs NEXT_PUBLIC_DEMO_* flags baked in at build time so- # the published ghcr.io/beenuar/aisoc-web image used by `pnpm aisoc:demo`- # ships a bundle that knows it's a demo (banner, auto-login, deeplink).- # Without these the bundle has empty strings → demo affordances no-op- # and visitors get bounced to /login on first navigation. Other images- # (api/agents/realtime) gate demo behavior at runtime via AISOC_DEMO_MODE- # so they don't need build args. The Dockerfile already defaults these- # to demo values; setting them here is explicit-is-better-than-implicit.+ type=raw,value=main,enable=${{ github.ref == 'refs/heads/main' && matrix.demo != 'true' }}+ type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' && matrix.demo != 'true' }}+ type=sha,prefix=sha-,format=short,enable=${{ matrix.demo != 'true' }}+ type=raw,value=demo,enable=${{ github.ref == 'refs/heads/main' && matrix.demo == 'true' }}+ type=sha,prefix=demo-sha-,format=short,enable=${{ matrix.demo == 'true' }}++ # Only the `demo` tag gets the NEXT_PUBLIC_DEMO_* flags. Next inlines+ # them at build time, so this is the whole difference between the two+ # images — and why it has to be a separate build rather than a runtime+ # switch. Other images (api/agents/realtime) gate demo behaviour at+ # runtime via AISOC_DEMO_MODE and need no build args at all.+ #+ # The credentials are supplied here rather than defaulted in the+ # Dockerfile so a build that does not ask for the demo cannot inline+ # them into a bundle it ships to a customer.- id: web-build-args- if: matrix.service == 'web'+ if: matrix.demo == 'true'run: |{echo 'build_args<<EOF'diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 2143505ca..273a36d2f 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -119,6 +119,17 @@ jobs:dockerfile: apps/web/Dockerfileimage: ghcr.io/beenuar/aisoc-web+ # The demo build of the console. Kept off `vX.Y.Z` and `latest` — see+ # the matching entry in publish-images.yml for why: Next inlines+ # NEXT_PUBLIC_* at build time, so a demo bundle on the tag a+ # self-hoster pulls is a console that calls their real data a demo,+ # with no runtime way out.+ - service: web-demo+ context: .+ dockerfile: apps/web/Dockerfile+ image: ghcr.io/beenuar/aisoc-web+ demo: 'true'+# Full-stack backend images (pulled by `docker compose up -d` with# `pull_policy: missing` when AISOC_VERSION is pinned).- service: ingest@@ -170,13 +181,13 @@ jobs:username: ${{ github.actor }}password: ${{ secrets.GITHUB_TOKEN }}- # Web image needs NEXT_PUBLIC_DEMO_* flags baked in at build time so the- # released ghcr.io/beenuar/aisoc-web:vX.Y.Z image (used by AISOC_VERSION- # pinning) ships a bundle that knows it's a demo. Mirrors the same step- # in publish-images.yml. Other images gate demo behavior at runtime via- # AISOC_DEMO_MODE so they don't need build args.+ # Only the demo build gets the NEXT_PUBLIC_DEMO_* flags, and only it is+ # published under a demo tag. Mirrors publish-images.yml. Other images+ # gate demo behaviour at runtime via AISOC_DEMO_MODE so they need no+ # build args. The credentials live here rather than in the Dockerfile so+ # a non-demo build cannot inline them into a shipped bundle.- id: web-build-args- if: matrix.service == 'web'+ if: matrix.demo == 'true'run: |{echo 'build_args<<EOF'@@ -188,15 +199,30 @@ jobs:echo 'EOF'} >> "$GITHUB_OUTPUT"+ # `vX.Y.Z-demo` is pinnable the same way `vX.Y.Z` is, and `demo` tracks+ # the newest one. Neither `vX.Y.Z` nor `latest` ever carries a demo+ # bundle.+ - id: image-tags+ run: |+ {+ echo 'tags<<EOF'+ if [ "${{ matrix.demo }}" = "true" ]; then+ echo "${{ matrix.image }}:${{ github.ref_name }}-demo"+ echo "${{ matrix.image }}:demo"+ else+ echo "${{ matrix.image }}:${{ github.ref_name }}"+ echo "${{ matrix.image }}:latest"+ fi+ echo 'EOF'+ } >> "$GITHUB_OUTPUT"+- id: builduses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7with:context: ${{ matrix.context }}file: ${{ matrix.context }}/${{ matrix.dockerfile }}push: true- tags: |- ${{ matrix.image }}:${{ github.ref_name }}- ${{ matrix.image }}:latest+ tags: ${{ steps.image-tags.outputs.tags }}build-args: ${{ steps.web-build-args.outputs.build_args }}cache-from: type=gha,scope=${{ matrix.service }}cache-to: type=gha,mode=max,scope=${{ matrix.service }}diff --git a/CHANGELOG.md b/CHANGELOG.mdindex dd7e70d06..55a8c7435 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -643,6 +643,96 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0`retry_max` at 5 against a model allowing 25 — and is now generated from`StepType` and `bounds.py`.+- **A new user who followed only the README could not log in.** `make up`+ worked, `make smoke` passed 8/8, and then authentication was impossible for+ three independent reasons at once. The only account was `[email protected]`,+ and `LoginRequest.email` is a pydantic `EmailStr`, which rejects RFC 6761+ special-use domains — so the address returned `HTTP 422 "value is not a+ valid email address: The part after the @-sign is a special-use or reserved+ name"` *before the password was ever compared*. The bcrypt hash migration+ 001 seeded matched neither the `changeme` that four documentation pages+ published nor the `admin` its own inline comment claimed; checked with this+ service's `verify_password`, every candidate returned `False`, so it+ corresponded to no known secret. And nothing existed to create a user with.+ `make demo` repaired it incidentally by writing a valid address, which left+ the demo path working and the path for running AiSOC on your own data+ broken.++ The first administrator is now created by the deployment rather than+ committed to the repository. `services/api/app/scripts/bootstrap_admin.py`+ creates `[email protected]`, generates a password, and prints it once —+ it is stored nowhere. `make up` calls it, so the documented quick start ends+ with a credential on screen; `make bootstrap` runs it on its own and+ `make bootstrap ARGS=--reset-password` mints a new one. It is idempotent: a+ second run reports the existing account and changes nothing, which is what+ makes it safe for `make up` to call unconditionally. The address is+ validated with the same library the login route uses, so an address that+ cannot sign in is refused here with an explanation instead of becoming an+ account that fails at a login form with a schema error.++ Migration 001 no longer seeds a user at all, and `059` deactivates the+ orphaned row on databases that already ran it. A gate+ (`tests/test_first_run_gate.py`) now asserts that no migration ships a+ password hash and that every login example in the documentation uses an+ address the API accepts — the four pages were each self-consistent with the+ broken seed, which is why reading them found nothing.+ `golden-pipeline.yml` runs `make bootstrap` against the live stack and+ authenticates with the credential it printed, so the quick start's last step+ is covered by the same job that covers its first.++- **The published `aisoc-web:latest` image shipped demo mode baked on**, and+ it is the image `docker-compose.yml` pulls for `make up`. Next inlines+ `NEXT_PUBLIC_*` at build time, so there was no runtime escape: a+ self-hoster's console announced "Demo data resets daily at 00:00 UTC. All+ write actions are disabled." over their own real alerts, disabled every+ write control, and offered a "Self-host AiSOC" link inside an already+ self-hosted install. The only remedy was to rebuild the image.++ The demo is now its own build under its own tag. `latest`, `main` and+ `vX.Y.Z` are the product with demo mode off; `demo` and `vX.Y.Z-demo` carry+ the demo bundle, and `infra/compose/docker-compose.demo.yml` pulls those.+ Nothing has to choose between a working demo and a usable self-host image.++ Demo credentials are also no longer compiled into a non-demo bundle at all.+ `apps/web/Dockerfile` defaulted the autologin address and password to real+ values, and `login/page.tsx` and `DemoAutoLogin.tsx` each declared them as+ module-level literals — gating the *render* on `isDemoMode()` hid the panel+ but left the strings in every chunk the project ships. All three now read+ them from the build environment, and only the demo build supplies them.++- **`make up` printed an API docs URL that 404s.** The README was corrected on+ its own; the tooling was not, so `make up`, `install.sh`, `install.ps1`,+ `scripts/lab.sh` and three documentation pages went on telling every new+ user to open `http://localhost:8000/docs` while the app mounts `/api/docs`.+ `test_readme_api_docs_url.py` now walks the tool output as well as the+ README.++- **The README never told anyone to create `.env`.** `make doctor` correctly+ reported it missing and printed the fix; the quick start it was meant to+ support skipped the step. It is now the second line of the quick start.++- **`make doctor` reported a port held by a foreign process as held by us.**+ The check was `docker compose ps -q <service>`, which lists containers in+ any state — so a Postgres that exited *because* the port was taken still+ counted, and the doctor printed "port 5432 in use by aisoc postgres" while+ an unrelated process had it. The two remedies are opposites. It now asks+ which host port our own container actually publishes, names the container or+ process that holds the port otherwise, and reports a service already+ remapped to a different port as fine rather than as a conflict.++- **`make up` hit port conflicts with no explanation.** `docker compose up`+ reports `port is already allocated` against whichever container lost the+ race, after a minute of unrelated output and without naming what holds it.+ `make up` now runs the port check first (`doctor.sh --ports-only`) and stops+ before starting anything.++- **The compose security note recommended a remedy that does nothing.** Both+ compose files told operators to change a host binding with a+ `docker-compose.override.yml`. Compose *appends* sequences when it merges,+ so an override without `!override` publishes the new binding alongside the+ old one and leaves the conflict in place. Both notes now show the tag, and+ `ports: !reset []` for removing a publishing entirely.+- **The agent recommended evidence acquisition the platform could notperform.** `capture_forensics` was an `ActionType` with no executoranywhere, and `services/agents/app/agents/investigation_agent.py` proposesdiff --git a/Makefile b/Makefileindex 0147b9c0f..69184f0a2 100644--- a/Makefile+++ b/Makefile@@ -24,7 +24,8 @@ PROFILE ?=PROFILE_ARG := $(if $(PROFILE),--profile $(PROFILE),).PHONY: help install up up-full down restart status doctor smoke demo logs clean \- test test-unit test-integration test-e2e stats papers papers-install demo-script+ bootstrap test test-unit test-integration test-e2e stats papers \+ papers-install demo-scripthelp:@echo ""@@ -32,6 +33,7 @@ help:@echo " make install Install prerequisites, configure, start, and verify"@echo " make up Start the CORE stack (postgres, kafka, ingest, fusion, api, web)"@echo " make up-full Start CORE plus lake, graph, vector, search and enrichment"+ @echo " make bootstrap Create the first administrator and print its password once"@echo " make smoke Push one real event through the pipeline and check it becomes an alert"@echo " make doctor Diagnose the deployment and say what to fix"@echo ""@@ -54,16 +56,40 @@ help:install:./install.sh-up:+# The port check runs before compose, not after it fails. `docker compose up`+# reports a conflict as `Bind for 127.0.0.1:5432 failed: port is already+# allocated` against whichever container lost the race, which names neither the+# process holding the port nor what to do about it. Half the stack is running+# by then, so the error also arrives after a minute of unrelated output.+up: _ports$(COMPOSE) up -d@echo ""@echo "Waiting for services to become healthy…"@$(MAKE) --no-print-directory _wait@echo ""@echo " Console: http://localhost:3000"- @echo " API: http://localhost:8000/docs"+ @echo " API: http://localhost:8000/api/docs"@echo ""@echo "Prove the pipeline works: make smoke"+ @$(MAKE) --no-print-directory bootstrap++# Creates the first administrator and prints the password once. Idempotent: a+# second run reports the existing account and changes nothing, which is why+# `up` can call it unconditionally.+#+# Failure here is reported but does not fail `up`. The stack is genuinely+# running at this point, and a `make up` that exits non-zero over an account+# the operator can create with one more command would be the wrong signal —+# but it must say so, because silence would leave them at a login form with no+# credential and no explanation.+# `make bootstrap ARGS=--reset-password` replaces the password of an account+# that already exists, which is the answer to "the terminal scrolled away".+bootstrap:+ @$(COMPOSE) run --rm -T api python -m app.scripts.bootstrap_admin $(ARGS) || { \+ echo ""; \+ echo "Could not create the administrator — the stack is up, but you cannot sign in yet."; \+ echo "Run 'make doctor' to find out why, then 'make bootstrap' again."; \+ }# The lake and graph writers target stores that exist only in `full`, so the# flags travel with the profile. In CORE they default off rather than@@ -73,6 +99,19 @@ up-full:@$(MAKE) --no-print-directory _wait@echo "Full profile up. Prove the pipeline works: make smoke"+# Names a port conflict before compose hits it. Silent when every port is+# either free or already held by this deployment's own containers — re-running+# `make up` on a running stack must not be reported as a conflict with itself.+_ports:+ @./scripts/doctor.sh --ports-only || { \+ echo ""; \+ echo "Not starting: the ports above are taken by something else."; \+ echo "Stop that process, or edit the host port in docker-compose.yml."; \+ echo "(A docker-compose.override.yml needs 'ports: !override' — a plain"; \+ echo " override appends, leaving the conflicting binding in place.)"; \+ exit 1; \+ }+# Waits on the services that declare a healthcheck. Silent on success._wait:@for i in $$(seq 1 60); do \diff --git a/README.md b/README.mdindex cced87168..9fcd7af49 100644--- a/README.md+++ b/README.md@@ -40,9 +40,15 @@ recorded, and proposes an action. A human approves before anything executes.```bashgit clone https://github.com/beenuar/AiSOC && cd AiSOC+cp .env.example .envmake up```+`make up` finishes by creating an administrator and printing its password.+That password is generated on your machine, shown once, and stored nowhere —+copy it before the terminal scrolls. If you lose it, mint a new one with+`make bootstrap ARGS=--reset-password`.+Then **prove it actually works** — this is the part that matters:```bash@@ -59,7 +65,8 @@ of the public API. Every stage reports PASS or FAIL:[PASS] alert is retrievable by id from the API```-Open **http://localhost:3000** (API docs at **http://localhost:8000/api/docs**).+Open **http://localhost:3000** and sign in with the credentials `make up`+printed (API docs at **http://localhost:8000/api/docs**).Something wrong? `make doctor` checks every dependency and tells you what torun next. Requires Docker with ~6 GB of RAM.diff --git a/apps/docs/docs/api/rest.md b/apps/docs/docs/api/rest.mdindex f0c558f78..34f0eee09 100644--- a/apps/docs/docs/api/rest.md+++ b/apps/docs/docs/api/rest.md@@ -18,11 +18,14 @@ AiSOC exposes a fully documented OpenAPI 3.1 REST API.### JWT Bearer (User)+Use the administrator `make bootstrap` created. There are no default+credentials — the password is generated per deployment and printed once.+```bash# Obtain a tokencurl -X POST http://localhost:8000/api/v1/auth/login \-H "Content-Type: application/json" \- -d '{"email":"[email protected]","password":"changeme"}'+ -d '{"email":"[email protected]","password":"<the password make up printed>"}'# Use the tokencurl http://localhost:8000/api/v1/cases \@@ -42,9 +45,9 @@ API keys are created via `POST /api/v1/api-keys` and can be scoped to specific pWhen running locally, interactive Swagger UI is available at:-- **Swagger UI**: [http://localhost:8000/docs](http://localhost:8000/docs)-- **ReDoc**: [http://localhost:8000/redoc](http://localhost:8000/redoc)-- **OpenAPI JSON**: [http://localhost:8000/openapi.json](http://localhost:8000/openapi.json)+- **Swagger UI**: [http://localhost:8000/api/docs](http://localhost:8000/api/docs)+- **ReDoc**: [http://localhost:8000/api/redoc](http://localhost:8000/api/redoc)+- **OpenAPI JSON**: [http://localhost:8000/api/openapi.json](http://localhost:8000/api/openapi.json)The full spec is also committed at [`docs/openapi.yaml`](https://github.com/beenuar/AiSOC/blob/main/docs/openapi.yaml).diff --git a/apps/docs/docs/architecture/overview.md b/apps/docs/docs/architecture/overview.mdindex df43edf5c..41245dbcf 100644--- a/apps/docs/docs/architecture/overview.md+++ b/apps/docs/docs/architecture/overview.md@@ -112,7 +112,7 @@ AiSOC/## API surface-The full OpenAPI 3.1 spec lives at [`docs/openapi.yaml`](https://github.com/beenuar/AiSOC/blob/main/docs/openapi.yaml). Endpoint groups are summarised in [Architecture](../architecture.md#api-surface) and the interactive view is at `http://localhost:8000/docs` (Swagger) or `/redoc` (ReDoc) when you run the local stack.+The full OpenAPI 3.1 spec lives at [`docs/openapi.yaml`](https://github.com/beenuar/AiSOC/blob/main/docs/openapi.yaml). Endpoint groups are summarised in [Architecture](../architecture.md#api-surface) and the interactive view is at `http://localhost:8000/api/docs` (Swagger) or `/api/redoc` (ReDoc) when you run the local stack.## Next stopsdiff --git a/apps/docs/docs/deployment/docker.md b/apps/docs/docs/deployment/docker.mdindex 14308f15d..5466dc8aa 100644--- a/apps/docs/docs/deployment/docker.md+++ b/apps/docs/docs/deployment/docker.md@@ -149,6 +149,26 @@ ghcr.io/beenuar/aisoc-enrichment:<version>ghcr.io/beenuar/aisoc-web:<version>```+### Image tags++| Tag | What it is | Who pulls it |+|---|---|---|+| `vX.Y.Z` | A pinned release. | `AISOC_VERSION` in `.env`, the Helm chart |+| `latest` | The newest release. | `docker-compose.yml`, so `make up` |+| `main` | The newest commit on `main`. | Anyone tracking the tip |+| `vX.Y.Z-demo`, `demo` | `aisoc-web` only: the console built for a public demo. | `infra/compose/docker-compose.demo.yml` |++The demo tags exist because the console's demo mode is a **build-time** choice,+not a runtime one: Next.js inlines `NEXT_PUBLIC_*` values into the client+bundle during `next build`, so an image built for a demo cannot be turned back+into a product image by changing an environment variable.++`latest` used to be that demo build, which meant a self-hosted console+announced that its data was demo data, disabled every write control and+offered a link to self-host an install that was already self-hosted, with no+way out short of rebuilding the image. Only `aisoc-web` is affected — the+other services gate demo behaviour at runtime through `AISOC_DEMO_MODE`.+### Image provenanceEach image is signed with [Cosign](https://docs.sigstore.dev/cosign/overview/)diff --git a/apps/docs/docs/quickstart.md b/apps/docs/docs/quickstart.mdindex 37a1907aa..66ae4997b 100644--- a/apps/docs/docs/quickstart.md+++ b/apps/docs/docs/quickstart.md@@ -198,7 +198,29 @@ CI on every PR — see### 7. Open the UIVisit [http://localhost:3000](http://localhost:3000) and log in with the-default seeded credentials: `[email protected]` / `changeme`.+credentials `make up` printed.++There are no default credentials. `make up` runs `make bootstrap`, which+creates `[email protected]` with a password generated on your machine and+printed once — it is stored nowhere, so copy it when you see it. If the+terminal has already scrolled away, mint a new one:++```bash+make bootstrap ARGS=--reset-password+```++To choose the address or supply your own password instead:++```bash[email protected] make bootstrap+printf '%s' "$MY_PASSWORD" | docker compose run --rm -T api \+ python -m app.scripts.bootstrap_admin --password-stdin+```++The address has to be one the login route accepts. It is validated with the+same library the API uses, so reserved domains (`.local`, `.test`, `.invalid`,+`.localhost`) are refused here with an explanation rather than producing an+account that fails at the login form with a schema error.The mobile **Responder PWA** lives at[http://localhost:3000/responder](http://localhost:3000/responder) — installdiff --git a/apps/web/Dockerfile b/apps/web/Dockerfileindex 9f831a04b..95937bb11 100644--- a/apps/web/Dockerfile+++ b/apps/web/Dockerfile@@ -72,11 +72,19 @@ ENV NEXT_PUBLIC_WS_URL=${NEXT_PUBLIC_WS_URL}# `infra/compose/docker-compose.demo.yml`), so the safe default costs those# nothing. The api/agents/realtime images are unaffected — demo gating in# those services is runtime via AISOC_DEMO_MODE, not build-time.+# The autologin credentials default to empty, and deliberately carry no+# fallback anywhere else either. They used to default to a real address and+# password here, which meant every image — including one built with demo mode+# off — inlined a working login pair into the JavaScript it serves to browsers.+# A build that does not ask for the demo should not be able to ship demo+# credentials by omission. Every demo path passes them explicitly+# (`publish-images.yml`, `release.yml`, `infra/fly/web/fly.toml`, the `build:`+# block below this file's consumers), so the empty default costs those nothing.ARG NEXT_PUBLIC_DEMO_MODE=""ARG NEXT_PUBLIC_DEMO_DEEPLINK="/cases/INC-RT-001?tab=ledger"ARG NEXT_PUBLIC_DEMO_BANNER="Demo data resets daily at 00:00 UTC. All write actions are disabled."-ARG NEXT_PUBLIC_DEMO_AUTOLOGIN_EMAIL="[email protected]"-ARG NEXT_PUBLIC_DEMO_AUTOLOGIN_PASSWORD="aisoc-demo"+ARG NEXT_PUBLIC_DEMO_AUTOLOGIN_EMAIL=""+ARG NEXT_PUBLIC_DEMO_AUTOLOGIN_PASSWORD=""ENV NEXT_PUBLIC_DEMO_MODE=${NEXT_PUBLIC_DEMO_MODE}ENV NEXT_PUBLIC_DEMO_DEEPLINK=${NEXT_PUBLIC_DEMO_DEEPLINK}ENV NEXT_PUBLIC_DEMO_BANNER=${NEXT_PUBLIC_DEMO_BANNER}diff --git a/apps/web/src/app/login/page.tsx b/apps/web/src/app/login/page.tsxindex 0fedbb2fb..023686736 100644--- a/apps/web/src/app/login/page.tsx+++ b/apps/web/src/app/login/page.tsx@@ -22,8 +22,15 @@ type Phase = 'idle' | 'pending' | 'success' | 'error';export const dynamic = 'force-dynamic';-const DEMO_EMAIL = '[email protected]';-const DEMO_PASSWORD = 'aisoc-demo';+// Supplied by the build, never written here. Next inlines NEXT_PUBLIC_* into+// the client bundle wherever they are referenced, so a literal in this module+// would put a working login pair into every image the project ships —+// including one built with demo mode off for somebody's own deployment.+// Gating the *render* on isDemoMode() hides the panel; it does not remove the+// strings. Only the demo build passes these.+const DEMO_EMAIL = process.env.NEXT_PUBLIC_DEMO_AUTOLOGIN_EMAIL?.trim() ?? '';+const DEMO_PASSWORD = process.env.NEXT_PUBLIC_DEMO_AUTOLOGIN_PASSWORD?.trim() ?? '';+const HAS_DEMO_CREDENTIALS = Boolean(DEMO_EMAIL && DEMO_PASSWORD);/*** Sanitize the ``?next=`` redirect target so a crafted link can't be used to@@ -126,19 +133,19 @@ function LoginInner() {</p></div>- {/* Demo banner — demo mode only.- These credentials are seeded by the public demo and exist- nowhere else, so on a self-hosted deployment this rendered a- "Use demo" button that fails and told the operator's own users- to sign in with an account on somebody else's instance. */}- {isDemoMode() && (+ {/* Demo banner — demo mode only, and only when the build supplied+ credentials. These are seeded by a public demo and exist nowhere+ else, so on a self-hosted deployment this rendered a "Use demo"+ button that fails and told the operator's own users to sign in+ with an account on somebody else's instance. */}+ {isDemoMode() && HAS_DEMO_CREDENTIALS && (<div className="mb-6 rounded-xl border border-indigo-500/30 bg-indigo-500/5 px-4 py-3 text-sm"><div className="flex items-start justify-between gap-3"><div><p className="font-medium text-indigo-300">Public demo</p><p className="text-xs text-zinc-400 mt-0.5">- <code className="text-zinc-300">[email protected]</code> /{' '}- <code className="text-zinc-300">aisoc-demo</code>+ <code className="text-zinc-300">{DEMO_EMAIL}</code> /{' '}+ <code className="text-zinc-300">{DEMO_PASSWORD}</code></p></div><buttondiff --git a/apps/web/src/components/demo/DemoAutoLogin.tsx b/apps/web/src/components/demo/DemoAutoLogin.tsxindex c2b57934c..db7f73b53 100644--- a/apps/web/src/components/demo/DemoAutoLogin.tsx+++ b/apps/web/src/components/demo/DemoAutoLogin.tsx@@ -3,18 +3,21 @@/*** DemoAutoLogin — silent auto-login for a public demo deployment.*- * On the public demo we never want a visitor to land on `/cases` and see mock+ * On a public demo we never want a visitor to land on `/cases` and see mock* rows because no JWT is in `localStorage`. This component runs once on mount* inside `AppShell`, and when:** 1. `isDemoMode()` is true (NEXT_PUBLIC_DEMO_MODE=true), AND- * 2. there's no existing access token,+ * 2. the build supplied demo credentials, AND+ * 3. there's no existing access token,*- * it logs in as the well-known demo user (`[email protected]` / `aisoc-demo` —- * the same credentials displayed on `/login`) and then triggers a global SWR- * revalidation so every `useSWR` hook on the page swaps its `fallbackData`+ * it logs in as the demo user the deployment seeded and then triggers a global+ * SWR revalidation so every `useSWR` hook on the page swaps its `fallbackData`* mocks for the freshly-fetched live data.*+ * The credentials come only from the build environment, never from a literal+ * in this file — see the constants below.+ ** Renders nothing. Failures are swallowed silently — most demo endpoints* (cases list, alerts list, dashboard widgets) work without a JWT thanks to* the demo tenant default, so a failed auto-login still leaves the page@@ -28,10 +31,13 @@ import { useSWRConfig } from 'swr';import { authApi } from '@/lib/api';import { isDemoMode } from '@/lib/demoMode';-const DEMO_EMAIL =- process.env.NEXT_PUBLIC_DEMO_AUTOLOGIN_EMAIL?.trim() || '[email protected]';-const DEMO_PASSWORD =- process.env.NEXT_PUBLIC_DEMO_AUTOLOGIN_PASSWORD?.trim() || 'aisoc-demo';+// No fallback literals. These are inlined by Next at build time wherever they+// are referenced, so a hardcoded default here would put a working login pair+// into the bundle of every build — including one made with demo mode off and+// shipped to somebody's own deployment. A demo build passes them explicitly;+// anything else gets empty strings and the effect below does nothing.+const DEMO_EMAIL = process.env.NEXT_PUBLIC_DEMO_AUTOLOGIN_EMAIL?.trim() ?? '';+const DEMO_PASSWORD = process.env.NEXT_PUBLIC_DEMO_AUTOLOGIN_PASSWORD?.trim() ?? '';export function DemoAutoLogin() {const { mutate } = useSWRConfig();@@ -40,6 +46,7 @@ export function DemoAutoLogin() {// Only run client-side. Demo flag is build-time inlined, but we double// check at runtime so a test override via `__setDemoModeForTests` works.if (!isDemoMode()) return;+ if (!DEMO_EMAIL || !DEMO_PASSWORD) return;if (typeof window === 'undefined') return;// Already authenticated? Nothing to do — let the existing session ride.diff --git a/docker-compose.yml b/docker-compose.ymlindex 23fda3ab4..828096411 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -9,10 +9,23 @@# `docker compose up` does NOT expose Postgres / Kafka / OpenSearch /# Neo4j / Redis (with their development passwords) to the network the# host is attached to. This is intentional: the same passwords ship in-# every clone of this repo. If you need to reach these from another-# machine, write a docker-compose.override.yml that changes the host-# binding for the specific service you're exposing — and rotate the-# password while you're there.+# every clone of this repo.+#+# To change a binding, write a docker-compose.override.yml and tag the list+# `!override`:+#+# services:+# postgres:+# ports: !override+# - "0.0.0.0:5432:5432"+#+# The tag is not optional. Compose *appends* sequences when it merges, so an+# override without it publishes both the old binding and the new one — the+# 127.0.0.1 binding stays, and on a port that was already taken the conflict+# is still there. It looks like it worked and it did nothing. Use+# `ports: !reset []` to stop publishing a service on the host entirely.+#+# Rotate the password while you're there.###############################################################################networks:diff --git a/docs/api/API_REFERENCE.md b/docs/api/API_REFERENCE.mdindex fcbbccd43..4cb77efab 100644--- a/docs/api/API_REFERENCE.md+++ b/docs/api/API_REFERENCE.md@@ -15,9 +15,12 @@ This document describes the REST endpoints exposed by AiSOC services. For the auAll examples assume:```bash+# AISOC_ADMIN_PASSWORD is the password `make bootstrap` printed. There is no+# default credential — each deployment generates its own at first run.export AISOC_TOKEN="$(curl -sX POST http://localhost:8000/v1/auth/login \-H 'content-type: application/json' \- -d '{"email":"[email protected]","password":"changeme"}' | jq -r .access_token)"+ -d "{\"email\":\"[email protected]\",\"password\":\"$AISOC_ADMIN_PASSWORD\"}" \+ | jq -r .access_token)"export AISOC_TENANT="00000000-0000-0000-0000-000000000001"```diff --git a/docs/runbooks/LOCAL_DEVELOPMENT.md b/docs/runbooks/LOCAL_DEVELOPMENT.mdindex bfbdef801..ad121ec20 100644--- a/docs/runbooks/LOCAL_DEVELOPMENT.md+++ b/docs/runbooks/LOCAL_DEVELOPMENT.md@@ -125,7 +125,7 @@ poetry run python -m app.scripts.run_migrations # apply DB migrations (forwardpoetry run uvicorn app.main:app --reload --port 8000```-Browse `http://localhost:8000/docs`.+Browse `http://localhost:8000/api/docs`.### 4.2 Fusion (`services/fusion`)@@ -201,10 +201,12 @@ Browse `http://localhost:3000`.## 5. Smoke-test path (≈ 5 minutes)```bash-# 1. Get a token+# 1. Get a token. AISOC_ADMIN_PASSWORD is the password `make bootstrap` printed+# — there is no default credential; each deployment generates its own.TOKEN=$(curl -s -X POST http://localhost:8000/v1/auth/login \-H 'content-type: application/json' \- -d '{"email":"[email protected]","password":"changeme"}' | jq -r .access_token)+ -d "{\"email\":\"[email protected]\",\"password\":\"$AISOC_ADMIN_PASSWORD\"}" \+ | jq -r .access_token)# 2. Send a synthetic event into Kafkadocker exec -i aisoc-kafka kafka-console-producer \diff --git a/infra/compose/docker-compose.demo.yml b/infra/compose/docker-compose.demo.ymlindex 1305d80ed..46194c51f 100644--- a/infra/compose/docker-compose.demo.yml+++ b/infra/compose/docker-compose.demo.yml@@ -41,10 +41,22 @@# -------------# Host port publishings below are bound to 127.0.0.1 so the demo's# development passwords are not exposed on the LAN. The same passwords-# ship with every clone of this repo. If you need to reach these from-# another machine, write a docker-compose.override.yml that changes-# the host binding for the specific service you're exposing — and-# rotate the password while you're there.+# ship with every clone of this repo.+#+# To change a binding, write a docker-compose.override.yml and tag the+# list `!override`:+#+# services:+# postgres:+# ports: !override+# - "0.0.0.0:5432:5432"+#+# The tag is not optional. Compose *appends* sequences when it merges, so+# an override without it publishes both the old binding and the new one,+# leaving the 127.0.0.1 binding in place. It looks like it worked and it+# did nothing. Use `ports: !reset []` to stop publishing on the host.+#+# Rotate the password while you're there.###############################################################################name: aisoc-demo@@ -286,7 +298,11 @@ services:command: ["python", "-m", "app.scripts.seed_demo"]web:- image: ghcr.io/beenuar/aisoc-web:${AISOC_TAG:-latest}+ # `demo`, not `latest`. `latest` is the product build with demo mode off —+ # pulling it here would give a demo stack with no banner, no auto-login and+ # a visitor bounced to /login on first navigation. The two tags are built+ # from the same commit by publish-images.yml.+ image: ghcr.io/beenuar/aisoc-web:${AISOC_TAG:-demo}# Build context for `pnpm aisoc:demo --rebuild`. The Dockerfile bakes the# frontend bundle with empty NEXT_PUBLIC_* defaults so every fetch is a# same-origin relative path (`/api/v1/...`, `/ws/...`). Next.js thendiff --git a/install.ps1 b/install.ps1index 3b04fde63..d24204a0a 100644--- a/install.ps1+++ b/install.ps1@@ -731,7 +731,7 @@ function Write-SuccessBanner {Write-Host ''Write-Host ' Web console: http://localhost:3000'Write-Host ' Showcase case: http://localhost:3000/cases/INC-RT-001?tab=ledger'- Write-Host ' API + Swagger: http://localhost:8000/docs'+ Write-Host ' API + Swagger: http://localhost:8000/api/docs'Write-Host ' Realtime WS: ws://localhost:8086'Write-Host ''Write-Host "Useful commands (run from $RepoRoot):" -ForegroundColor DarkGraydiff --git a/install.sh b/install.shindex 69d465e40..53227318a 100755--- a/install.sh+++ b/install.sh@@ -854,10 +854,13 @@ print_success() {${C_BOLD}${C_GREEN}AiSOC is up and running${C_RESET}${C_GREEN}, and a real event reached the API.${C_RESET}${C_BOLD}Web console:${C_RESET} http://localhost:3000- ${C_BOLD}Showcase case:${C_RESET} http://localhost:3000/cases/INC-RT-001?tab=ledger- ${C_BOLD}API + Swagger:${C_RESET} http://localhost:8000/docs+ ${C_BOLD}API + Swagger:${C_RESET} http://localhost:8000/api/docs${C_BOLD}Realtime WS:${C_RESET} ws://localhost:8086+ ${C_BOLD}Sign in as:${C_RESET} ${AISOC_ADMIN_EMAIL:[email protected]}+ The password was printed above, once, when the administrator was created.+ It is not stored anywhere. Lost it? make bootstrap ARGS=--reset-password+${C_DIM}Useful commands (run from $REPO_ROOT):${C_RESET}make doctor # diagnose every dependency, with the fix for eachmake smoke # re-run the end-to-end pipeline checkdiff --git a/scripts/doctor.sh b/scripts/doctor.shindex c7006da9d..5a9c60906 100755--- a/scripts/doctor.sh+++ b/scripts/doctor.sh@@ -7,21 +7,24 @@# check must probe the thing it names: "the container is running" is not# evidence that the service works, and this script does not report it as such.#-# ./scripts/doctor.sh # diagnose the default (CORE) profile-# ./scripts/doctor.sh --full # also check the full-profile stores-# ./scripts/doctor.sh --quiet # only print problems+# ./scripts/doctor.sh # diagnose the default (CORE) profile+# ./scripts/doctor.sh --full # also check the full-profile stores+# ./scripts/doctor.sh --quiet # only print problems+# ./scripts/doctor.sh --ports-only # just the port check (what `make up` runs first)## Exit code is 0 only when every required check passes.set -uo pipefailPROFILE_FULL=0QUIET=0+PORTS_ONLY=0for arg in "$@"; docase "$arg" in--full) PROFILE_FULL=1 ;;--quiet) QUIET=1 ;;+ --ports-only) PORTS_ONLY=1 ;;-h|--help)- sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'+ sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'exit 0 ;;*) echo "unknown option: $arg" >&2; exit 2 ;;esac@@ -80,7 +83,10 @@ elsepass "docker compose v2 available"fi-if docker info >/dev/null 2>&1; then+# Skipped under --ports-only: `make up` runs that mode as a pre-flight, and the+# disk probe starts a container. Advisories about free space do not belong in+# the path between typing `make up` and the stack starting.+if [ "$PORTS_ONLY" = "0" ] && docker info >/dev/null 2>&1; then# Disk exhaustion inside the Docker VM corrupts Kafka's log dir and the# broker then reports healthy while refusing every request. That exact# failure cost hours, so it is checked before anything else.@@ -112,20 +118,71 @@ port_busy() {elif have ss; then ss -ltn 2>/dev/null | grep -q ":$1 "else return 1; fi}-# Only flags a port held by something that is NOT our own stack.-for spec in "5432 postgres" "6379 redis" "9092 kafka" "8000 api" "8081 ingest-worker" "3000 web"; do- port="${spec%% *}"; owner="${spec##* }"- if port_busy "$port"; then- if [ -n "$COMPOSE" ] && svc_running "$owner"; then- pass "port $port in use by aisoc $owner"- else- fail "port $port is held by another process (needed by $owner)" "lsof -nP -iTCP:$port -sTCP:LISTEN # then stop it, or change the host port in docker-compose.yml"++# Names whatever is holding a port. "Something else has it" is only actionable+# if the operator can tell what, so this reports a container name when Docker+# published the port and the listening process otherwise.+port_holder() {+ _ph_port="$1"+ if have docker; then+ _ph_name="$(docker ps --filter "publish=${_ph_port}" --format '{{.Names}}' 2>/dev/null | head -n1)"+ [ -n "${_ph_name:-}" ] && { printf 'container %s' "$_ph_name"; return 0; }+ fi+ if have lsof; then+ _ph_pid="$(lsof -nP -iTCP:"${_ph_port}" -sTCP:LISTEN -t 2>/dev/null | head -n1)"+ if [ -n "${_ph_pid:-}" ]; then+ _ph_cmd="$(ps -o comm= -p "${_ph_pid}" 2>/dev/null | sed 's#.*/##')"+ printf '%s (pid %s)' "${_ph_cmd:-unknown process}" "${_ph_pid}"+ return 0fi+ fi+ printf 'an unidentified process'+}++# Prints the host port this deployment's own container publishes for a+# service, or nothing.+#+# The old test was `docker compose ps -q <svc>`, which answers a different+# question: it lists containers in *any* state. A postgres that exited because+# the port was already taken still counted, so the port was reported as ours+# while a foreign process held it — a green tick on the one line that needed to+# be red, and the two remedies are opposites (leave it alone, versus stop the+# other process). Observed against a live stack: an ssh tunnel held 5432, this+# deployment's postgres was published on 55432, and the doctor said+# "port 5432 in use by aisoc postgres".+svc_published_port() {+ [ -n "$COMPOSE" ] || return 1+ _sp_mapped="$($COMPOSE port "$1" "$2" 2>/dev/null | tail -n1)"+ [ -n "${_sp_mapped:-}" ] || return 1+ printf '%s' "${_sp_mapped##*:}"+}++# host-port service container-port+for spec in "5432 postgres 5432" "6379 redis 6379" "9092 kafka 9092" \+ "8000 api 8000" "8081 ingest-worker 8080" "3000 web 3000"; do+ # shellcheck disable=SC2086 # deliberate word splitting of a fixed 3-field spec+ set -- $spec; port="$1"; owner="$2"; cport="$3"+ ours="$(svc_published_port "$owner" "$cport" || true)"++ if [ "${ours:-}" = "$port" ]; then+ pass "port $port in use by aisoc $owner"+ elif [ -n "${ours:-}" ]; then+ # Already remapped. The canonical port being busy is then irrelevant, and+ # failing on it would send the operator to fix something that is working.+ pass "aisoc $owner is published on $ours (not the default $port)"+ elif port_busy "$port"; then+ fail "port $port is held by $(port_holder "$port") — aisoc $owner needs it" \+ "stop it, or change the host port in docker-compose.yml. A docker-compose.override.yml must use 'ports: !override' — a plain override appends and leaves $port published."else[ "$QUIET" = "1" ] || printf '%s·%s port %s free\n' "$D" "$X" "$port"fidone+if [ "$PORTS_ONLY" = "1" ]; then+ [ "$FAILURES" -eq 0 ] && exit 0+ exit 1+fi+[ -z "$COMPOSE" ] && { printf '\n%sCannot check services without docker compose.%s\n' "$R" "$X"; exit 1; }# ── 3. Configuration ────────────────────────────────────────────────────────diff --git a/scripts/lab.sh b/scripts/lab.shindex 0f0a1a687..38aadf4a1 100755--- a/scripts/lab.sh+++ b/scripts/lab.sh@@ -145,7 +145,7 @@ banner "AiSOC Demo Lab is ready"echo ""echo -e " ${BOLD}Service URLs${NC}"echo -e " ${CYAN}Web App ${NC} http://localhost:3000"-echo -e " ${CYAN}API (REST) ${NC} http://localhost:8000/docs"+echo -e " ${CYAN}API (REST) ${NC} http://localhost:8000/api/docs"echo -e " ${CYAN}API (GraphQL) ${NC} http://localhost:8000/graphql"echo -e " ${CYAN}Agent Orchestrator${NC} http://localhost:8001/docs"echo -e " ${CYAN}Jaeger Tracing ${NC} http://localhost:16686"diff --git a/services/api/app/scripts/bootstrap_admin.py b/services/api/app/scripts/bootstrap_admin.pynew file mode 100644index 000000000..322e2e725--- /dev/null+++ b/services/api/app/scripts/bootstrap_admin.py@@ -0,0 +1,328 @@+"""Create the first administrator for a fresh deployment.++ docker compose run --rm api python -m app.scripts.bootstrap_admin+ # or, from the repo root:+ make bootstrap++Run it once after ``make up``. It creates the default tenant if it is missing,+creates an administrator, and prints the password exactly once. Nothing writes+the password to disk — if it scrolls away, re-run with ``--reset-password``.++Why this exists rather than a seeded row in ``001_init.sql``: a password hash+committed to a public repository is a default credential on every deployment+that ever clones it. The migration used to carry one, and because nobody could+say what plaintext it came from, the only account a new install had was an+account nobody could log into. The fix is not a better-known default — it is+that the deployment mints its own secret at first run and tells the operator+what it is.++Three properties the acceptance test depends on:++* **The address passes the API's own validator.** ``LoginRequest.email`` is a+ pydantic ``EmailStr``, which rejects the RFC 6761 special-use domains+ (``.local``, ``.test``, ``.invalid``, ``.localhost``) *before* the password is+ ever compared — a 422, not a 401. The seeded ``[email protected]`` could+ therefore never authenticate whatever its password was. This script validates+ with the same library the route does and refuses to create an account that+ cannot sign in, so the failure surfaces here with an explanation instead of at+ a login form with a schema error.+* **The operator knows the password**, because it was generated here and+ printed, or supplied by them.+* **Re-running is safe.** An existing administrator is reported and left alone;+ the password is only touched under an explicit ``--reset-password``.++This is not a dev-mode shortcut and does not consult ``AISOC_DEV_MODE``. It+creates a real account with a real secret and is the supported path in every+environment.+"""++from __future__ import annotations++import argparse+import asyncio+import os+import secrets+import string+import sys+import uuid++from email_validator import EmailNotValidError, validate_email+from sqlalchemy import func, select++from app.core.security import get_password_hash+from app.db.database import AsyncSessionLocal+from app.models.tenant import Tenant, User++# Matches the tenant seeded by migration 001. Reused so a bootstrap on an+# already-migrated database adopts that tenant rather than creating a second+# one that none of the seeded rows belong to.+DEFAULT_TENANT_ID = uuid.UUID("00000000-0000-0000-0000-000000000001")++# `.internal` is reserved by ICANN for private use and — unlike `.local`,+# `.test` and `.invalid` — is not on the email validator's special-use list, so+# it both reads as "this address is internal to your deployment" and passes+# validation. `test_bootstrap_admin.py` asserts that against the real validator,+# so if a future release adds `.internal` to that list CI goes red here rather+# than the next self-hoster discovering it at a login form.+DEFAULT_ADMIN_EMAIL = "[email protected]"+DEFAULT_ADMIN_USERNAME = "admin"++# Unambiguous alphabet: no O/0, l/1/I. The password is read off a terminal and+# typed into a browser, and a character the operator cannot transcribe is the+# same defect as a password nobody knows.+_ALPHABET = (+ "".join(c for c in string.ascii_uppercase if c not in "OI")+ + "".join(c for c in string.ascii_lowercase if c not in "l")+ + "".join(c for c in string.digits if c not in "01")+)+_GENERATED_PASSWORD_LENGTH = 24++# Long enough that a generated one cannot be mistaken for a placeholder and+# short enough to type. bcrypt caps input at 72 bytes; `get_password_hash`+# truncates, so anything beyond that is silently not part of the secret.+MIN_PASSWORD_LENGTH = 12+MAX_PASSWORD_LENGTH = 72+++class BootstrapError(RuntimeError):+ """A condition the operator has to resolve, reported without a traceback."""+++def generate_password() -> str:+ return "".join(secrets.choice(_ALPHABET) for _ in range(_GENERATED_PASSWORD_LENGTH))+++def validate_admin_email(email: str) -> str:+ """Return the normalised address, or raise if the API could not accept it.++ ``check_deliverability=False`` keeps this offline: an air-gapped install+ must be able to bootstrap, and a DNS lookup here would make the first-run+ path depend on egress. Syntax and the special-use domain list are what+ ``EmailStr`` enforces on the login route, and both are checked locally.+ """+ try:+ return validate_email(email, check_deliverability=False).normalized+ except EmailNotValidError as exc:+ raise BootstrapError(+ f"{email!r} cannot be used to sign in: {exc}\n"+ " The login route validates with the same library, so an account created with this\n"+ " address would be rejected before its password was checked. Reserved domains\n"+ " (.local, .test, .invalid, .localhost) are the usual cause; try a routable domain\n"+ f" or the default {DEFAULT_ADMIN_EMAIL}."+ ) from exc+++def validate_password(password: str) -> str:+ if len(password) < MIN_PASSWORD_LENGTH:+ raise BootstrapError(f"password is {len(password)} characters; the minimum is {MIN_PASSWORD_LENGTH}.")+ if len(password.encode("utf-8")) > MAX_PASSWORD_LENGTH:+ raise BootstrapError(+ f"password is longer than {MAX_PASSWORD_LENGTH} bytes, which bcrypt truncates — "+ "the part past the limit would not be part of the secret."+ )+ return password+++def resolve_password(args: argparse.Namespace) -> tuple[str, bool]:+ """Return ``(password, was_generated)``.++ Precedence is explicit-over-implicit: ``--password-stdin`` (so a secret+ never lands in shell history or `ps` output), then ``AISOC_ADMIN_PASSWORD``,+ then a fresh random one.+ """+ if args.password_stdin:+ password = sys.stdin.readline().rstrip("\n")+ if not password:+ raise BootstrapError("--password-stdin was given but stdin was empty.")+ return validate_password(password), False++ from_env = os.environ.get("AISOC_ADMIN_PASSWORD", "")+ if from_env:+ return validate_password(from_env), False++ return generate_password(), True+++async def _ensure_tenant(session) -> Tenant:+ """Adopt the migration-seeded tenant, else any existing one, else create it."""+ result = await session.execute(select(Tenant).where(Tenant.id == DEFAULT_TENANT_ID))+ tenant = result.scalar_one_or_none()+ if tenant is not None:+ return tenant++ # A deployment that was provisioned some other way already has a tenant;+ # attaching the administrator to a brand-new one would make them an admin+ # of nothing, with every existing alert invisible.+ result = await session.execute(select(Tenant).order_by(Tenant.created_at).limit(1))+ tenant = result.scalar_one_or_none()+ if tenant is not None:+ return tenant++ tenant = Tenant(+ id=DEFAULT_TENANT_ID,+ name="Default",+ slug="default",+ plan="enterprise",+ is_active=True,+ )+ session.add(tenant)+ await session.flush()+ return tenant+++async def bootstrap(+ *,+ email: str,+ password: str,+ username: str,+ reset_password: bool,+) -> tuple[str, bool]:+ """Create or adopt the administrator.++ Returns ``(email, credential_is_new)``. ``credential_is_new`` is False when+ an account already existed and was left untouched, which is what tells the+ caller not to print a password the operator cannot use.+ """+ email = validate_admin_email(email)+ validate_password(password)++ async with AsyncSessionLocal() as session:+ tenant = await _ensure_tenant(session)++ # Case-insensitive: Postgres `UNIQUE` on `email` is case-sensitive, so+ # `Admin@…` and `admin@…` are two rows, and a second bootstrap would+ # hand out a password for an account the operator does not realise is a+ # duplicate.+ result = await session.execute(select(User).where(func.lower(User.email) == email.lower()))+ user = result.scalar_one_or_none()++ if user is not None:+ if not reset_password:+ return email, False+ user.hashed_password = get_password_hash(password)+ user.is_active = True+ user.is_verified = True+ user.role = "admin"+ await session.commit()+ return email, True++ # An administrator under a different address still counts — re-running+ # after a rename should not quietly mint a second one.+ result = await session.execute(select(User).where(User.role == "admin", User.is_active.is_(True)).limit(1))+ existing_admin = result.scalar_one_or_none()+ if existing_admin is not None and not reset_password:+ return existing_admin.email, False++ session.add(+ User(+ tenant_id=tenant.id,+ email=email,+ username=username,+ hashed_password=get_password_hash(password),+ role="admin",+ is_active=True,+ is_verified=True,+ preferences={},+ )+ )+ await session.commit()+ return email, True+++def _print_credentials(email: str, password: str, *, generated: bool) -> None:+ """Report the new account, disclosing the password only if we invented it.++ A password the operator supplied through ``AISOC_ADMIN_PASSWORD`` or+ ``--password-stdin`` is never echoed: they already have it, and printing it+ back would put a secret on a terminal and into any scrollback or CI log for+ no gain. A generated one is printed because it exists nowhere else — that+ single line is the whole point of this command, and it is why the password+ is never written to disk.++ CodeQL flags the generated branch as ``py/clear-text-logging-sensitive-data``+ and is correct that it discloses a secret. It is dismissed as accepted risk+ rather than suppressed: without it nobody can sign in, which is the defect+ this script exists to fix. The exposure is as narrow as the design allows —+ stdout rather than a logger, only the generated password, and+ ``golden-pipeline.yml`` redacts the line before it reaches a CI log. The+ alternative worth building later is an out-of-band channel (a one-shot+ token redeemed in the console); until that exists, a terminal the operator+ is already looking at is the smallest surface available.+ """+ console = os.environ.get("AISOC_CONSOLE_URL", "http://localhost:3000")+ bar = "─" * 64+ print(f"\n{bar}")+ print(" Administrator created. Sign in at " + console)+ print(bar)+ print(f" Email {email}")+ if generated:+ print(f" Password {password}")+ print(bar)+ print(" This password was generated now and is not stored anywhere.")+ print(" Copy it before closing this terminal. Lost it? Re-run with")+ print(" --reset-password to mint a new one.")+ else:+ print(" Password (the one you supplied — not echoed)")+ print(bar)+ print()+++def build_parser() -> argparse.ArgumentParser:+ parser = argparse.ArgumentParser(+ prog="python -m app.scripts.bootstrap_admin",+ description="Create the first administrator for this deployment.",+ )+ parser.add_argument(+ "--email",+ default=os.environ.get("AISOC_ADMIN_EMAIL", DEFAULT_ADMIN_EMAIL),+ help=f"administrator address (default: {DEFAULT_ADMIN_EMAIL}, or AISOC_ADMIN_EMAIL)",+ )+ parser.add_argument(+ "--username",+ default=os.environ.get("AISOC_ADMIN_USERNAME", DEFAULT_ADMIN_USERNAME),+ help=f"display name (default: {DEFAULT_ADMIN_USERNAME})",+ )+ parser.add_argument(+ "--password-stdin",+ action="store_true",+ help="read the password from stdin instead of generating one",+ )+ parser.add_argument(+ "--reset-password",+ action="store_true",+ help="replace the password of an existing administrator",+ )+ return parser+++async def _run(args: argparse.Namespace) -> int:+ password, generated = resolve_password(args)+ email, credential_is_new = await bootstrap(+ email=args.email,+ password=password,+ username=args.username,+ reset_password=args.reset_password,+ )++ if not credential_is_new:+ console = os.environ.get("AISOC_CONSOLE_URL", "http://localhost:3000")+ print(f"\nAn administrator already exists: {email}")+ print(f"Sign in at {console}.")+ print("Forgotten the password? Re-run this command with --reset-password.\n")+ return 0++ _print_credentials(email, password, generated=generated)+ return 0+++def main() -> int:+ args = build_parser().parse_args()+ try:+ return asyncio.run(_run(args))+ except BootstrapError as exc:+ print(f"\nbootstrap failed: {exc}\n", file=sys.stderr)+ return 2+++if __name__ == "__main__": # pragma: no cover - module entrypoint+ raise SystemExit(main())diff --git a/services/api/migrations/001_init.sql b/services/api/migrations/001_init.sqlindex d52de6e9d..29764e284 100644--- a/services/api/migrations/001_init.sql+++ b/services/api/migrations/001_init.sql@@ -197,22 +197,33 @@ CREATE INDEX IF NOT EXISTS idx_rules_enabled ON detection_rules(enabled);CREATE INDEX IF NOT EXISTS idx_rules_type ON detection_rules(rule_type);-- ──────────────────────────────────────────────────────────────────────────────--- Seed: default tenant & admin user+-- Seed: default tenant-- ──────────────────────────────────────────────────────────────────────────────INSERT INTO tenants (id, name, slug, plan)VALUES ('00000000-0000-0000-0000-000000000001', 'Default', 'default', 'enterprise')ON CONFLICT (slug) DO NOTHING;--- password = "admin" (bcrypt)-INSERT INTO users (id, tenant_id, email, username, hashed_password, role, is_active, is_verified)-VALUES (- '00000000-0000-0000-0000-000000000002',- '00000000-0000-0000-0000-000000000001',- '[email protected]',- 'admin',- '$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewdBPj3EEbF7FtRS',- 'admin',- TRUE,- TRUE-) ON CONFLICT (email) DO NOTHING;+-- No administrator is seeded here, deliberately.+--+-- This migration used to insert '[email protected]' with a bcrypt hash and a+-- comment claiming the password was "admin". Both halves were wrong, and+-- together they made a fresh install impossible to sign into:+--+-- * `.local` is an RFC 6761 special-use domain. The login route validates+-- with pydantic `EmailStr`, which rejects it with a 422 *before* comparing+-- the password, so the address could never authenticate.+-- * The hash matched neither "admin" nor the "changeme" four documentation+-- pages published. Checked with the API's own `verify_password`, every+-- candidate returned False — it corresponded to no known secret.+--+-- A password hash committed here is also a default credential on every+-- deployment that clones this repository, which is the thing to avoid rather+-- than the thing to get right. The deployment mints its own secret instead:+--+-- make bootstrap+-- # docker compose run --rm api python -m app.scripts.bootstrap_admin+--+-- It is idempotent, validates the address against the same library the login+-- route uses, and prints the password once. See+-- services/api/app/scripts/bootstrap_admin.py.diff --git a/services/api/migrations/059_retire_unusable_seed_admin.sql b/services/api/migrations/059_retire_unusable_seed_admin.sqlnew file mode 100644index 000000000..0ff5186c6--- /dev/null+++ b/services/api/migrations/059_retire_unusable_seed_admin.sql@@ -0,0 +1,27 @@+-- 059: retire the administrator that migration 001 seeded and nobody could use.+--+-- 001 inserted '[email protected]' with a bcrypt hash whose plaintext is not+-- known. The address alone made it unusable — `.local` is an RFC 6761+-- special-use domain and the login route's pydantic `EmailStr` rejects it with+-- a 422 before the password is compared — and the hash matched none of the+-- passwords the documentation published either. 001 no longer seeds it, which+-- covers fresh installs; this covers databases that already ran 001.+--+-- The row is deactivated rather than deleted. Deleting is tempting for a row+-- that was never usable, but `005_compliance.sql` references users(id) with no+-- ON DELETE clause, so a DELETE can fail on a constraint instead of completing+-- quietly — and `is_active = FALSE` is enough: it is what the login route+-- filters on, and what bootstrap_admin.py checks before deciding an+-- administrator already exists.+--+-- Guarded on the id, address and exact hash together so it can only ever match+-- the row 001 wrote. seed_demo.py adopts this same id and rewrites all three+-- columns, so a demo deployment's user does not match and is left alone.++UPDATE users+SET is_active = FALSE,+ updated_at = NOW()+WHERE id = '00000000-0000-0000-0000-000000000002'+ AND email = '[email protected]'+ AND hashed_password = '$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewdBPj3EEbF7FtRS'+ AND last_login IS NULL;diff --git a/services/api/tests/test_bootstrap_admin.py b/services/api/tests/test_bootstrap_admin.pynew file mode 100644index 000000000..1d7deb3a6--- /dev/null+++ b/services/api/tests/test_bootstrap_admin.py@@ -0,0 +1,409 @@+"""A clean install has to end with an account somebody can actually sign into.++It did not. `make up` and `make smoke` both passed and then login was+impossible, for three independent reasons at once:++* the only account was `[email protected]`, and `LoginRequest.email` is a+ pydantic `EmailStr`, which rejects RFC 6761 special-use domains with a 422+ *before* the password is compared;+* the bcrypt hash migration 001 seeded matched neither the `changeme` four+ documentation pages published nor the `admin` its own inline comment claimed+ — checked with this service's `verify_password`, every candidate was False;+* nothing existed to create a user with.++So these tests assert the outcome, not the implementation: run the documented+command, and the credential it reports back authenticates. The email check runs+the real validator rather than a copy of its reserved-domain list, so if a+future `email_validator` release reclassifies the default domain this goes red+here instead of at a stranger's login form.+"""++from __future__ import annotations++import argparse+import io+import pathlib+import re+import uuid++import pytest+import pytest_asyncio+from app.core.security import verify_password+from app.db.database import Base+from app.models.tenant import Tenant, User+from app.scripts import bootstrap_admin as ba+from pydantic import BaseModel, EmailStr, ValidationError+from sqlalchemy import select+from sqlalchemy.dialects.postgresql import JSONB+from sqlalchemy.dialects.postgresql import UUID as PgUUID+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine+from sqlalchemy.ext.compiler import compiles++MIGRATIONS = pathlib.Path(__file__).resolve().parents[1] / "migrations"++# The hash migration 001 used to seed. Kept here so the test can prove the+# claim rather than restate it.+ORPHAN_HASH = "$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewdBPj3EEbF7FtRS"+++@compiles(JSONB, "sqlite")+def _jsonb_sqlite(_type_, _compiler_, **_kw_):+ return "TEXT"+++@compiles(PgUUID, "sqlite")+def _uuid_sqlite(_type_, _compiler_, **_kw_):+ return "CHAR(36)"+++class _LoginRequest(BaseModel):+ """The shape `POST /api/v1/auth/login` validates against."""++ email: EmailStr+++@pytest_asyncio.fixture+async def session_factory(monkeypatch):+ """An in-memory database wired in where the script reads its sessions.++ The contract under test is "an account exists and its password verifies",+ which is dialect-independent. Postgres-only column types are compiled down+ above.+ """+ engine = create_async_engine("sqlite+aiosqlite:///:memory:")+ async with engine.begin() as conn:+ # Only the two tables this touches. A whole-metadata create_all drags+ # in models using Postgres ARRAY, which SQLite cannot render.+ await conn.run_sync(Base.metadata.create_all, tables=[Tenant.__table__, User.__table__])+ factory = async_sessionmaker(engine, expire_on_commit=False)+ monkeypatch.setattr(ba, "AsyncSessionLocal", factory)+ yield factory+ await engine.dispose()+++async def _load_user(factory, email: str) -> User | None:+ async with factory() as session:+ result = await session.execute(select(User).where(User.email == email))+ return result.scalar_one_or_none()+++# ─── The defect this all exists for ──────────────────────────────────────────+++def test_the_address_migration_001_seeded_could_never_have_logged_in() -> None:+ with pytest.raises(ValidationError):+ _LoginRequest(email="[email protected]")+++def test_the_hash_migration_001_seeded_matched_no_documented_password() -> None:+ for candidate in ("admin", "changeme", "password", "aisoc", "[email protected]"):+ assert not verify_password(candidate, ORPHAN_HASH), (+ f"{candidate!r} verifies against the orphaned seed hash — if a password for it "+ "is known, the history in migration 059 needs correcting"+ )+++def test_migration_001_no_longer_seeds_an_administrator() -> None:+ sql = (MIGRATIONS / "001_init.sql").read_text()+ statements = re.findall(r"INSERT\s+INTO\s+users\b", sql, flags=re.IGNORECASE)+ assert not statements, (+ "001_init.sql seeds a user again. A password hash committed here is a default "+ "credential on every deployment that clones this repository; the first "+ "administrator is created by app.scripts.bootstrap_admin instead."+ )+++def test_no_migration_inserts_a_password_hash() -> None:+ offenders = [+ path.name+ for path in sorted(MIGRATIONS.glob("*.sql"))+ # 059 retires the orphan and has to name its hash to match only that row.+ if path.name != "059_retire_unusable_seed_admin.sql" and re.search(r"\$2[aby]\$\d\d\$", path.read_text())+ ]+ assert not offenders, f"migrations carrying a bcrypt hash: {offenders}"+++# ─── The default the tool hands out ──────────────────────────────────────────+++def test_the_default_address_passes_the_validator_the_login_route_uses() -> None:+ """Runs the real validator, so a reclassification of `.internal` fails here.++ Asserting against a copied list of reserved domains would pass forever+ while the route it is meant to mirror started rejecting the address.+ """+ assert _LoginRequest(email=ba.DEFAULT_ADMIN_EMAIL).email == ba.DEFAULT_ADMIN_EMAIL+++def test_a_reserved_domain_is_refused_here_rather_than_at_the_login_form() -> None:+ with pytest.raises(ba.BootstrapError) as exc:+ ba.validate_admin_email("[email protected]")+ assert "cannot be used to sign in" in str(exc.value)+++def test_generated_passwords_are_unique_and_transcribable() -> None:+ generated = {ba.generate_password() for _ in range(64)}+ assert len(generated) == 64, "generated passwords collided"+ for password in generated:+ assert len(password) >= ba.MIN_PASSWORD_LENGTH+ # Characters an operator reads off a terminal and retypes.+ assert not set(password) & set("O0lI1")+++def test_a_password_bcrypt_would_silently_truncate_is_refused() -> None:+ with pytest.raises(ba.BootstrapError):+ ba.validate_password("x" * (ba.MAX_PASSWORD_LENGTH + 1))+++# ─── The acceptance test, in miniature ───────────────────────────────────────+++async def test_the_printed_credential_authenticates(session_factory) -> None:+ password = ba.generate_password()++ email, is_new = await ba.bootstrap(+ email=ba.DEFAULT_ADMIN_EMAIL,+ password=password,+ username="admin",+ reset_password=False,+ )++ assert is_new+ user = await _load_user(session_factory, email)+ assert user is not None+ assert user.role == "admin"+ assert user.is_active+ # The whole point: this is what `POST /auth/login` does with the password.+ assert verify_password(password, user.hashed_password)+ # And this is what it does with the address first.+ assert _LoginRequest(email=user.email).email == email+++async def test_the_administrator_lands_in_the_tenant_the_migration_seeded(+ session_factory,+) -> None:+ """An admin of a brand-new tenant would see none of the existing alerts."""+ async with session_factory() as session:+ session.add(Tenant(id=ba.DEFAULT_TENANT_ID, name="Default", slug="default", plan="enterprise"))+ await session.commit()++ email, _ = await ba.bootstrap(+ email=ba.DEFAULT_ADMIN_EMAIL,+ password=ba.generate_password(),+ username="admin",+ reset_password=False,+ )++ user = await _load_user(session_factory, email)+ assert user is not None+ assert user.tenant_id == ba.DEFAULT_TENANT_ID+++async def test_it_creates_the_tenant_when_the_database_has_none(session_factory) -> None:+ await ba.bootstrap(+ email=ba.DEFAULT_ADMIN_EMAIL,+ password=ba.generate_password(),+ username="admin",+ reset_password=False,+ )+ async with session_factory() as session:+ tenants = (await session.execute(select(Tenant))).scalars().all()+ assert len(tenants) == 1+++async def test_it_adopts_an_existing_tenant_rather_than_adding_a_second(+ session_factory,+) -> None:+ other = uuid.uuid4()+ async with session_factory() as session:+ session.add(Tenant(id=other, name="Acme", slug="acme", plan="starter"))+ await session.commit()++ email, _ = await ba.bootstrap(+ email=ba.DEFAULT_ADMIN_EMAIL,+ password=ba.generate_password(),+ username="admin",+ reset_password=False,+ )++ user = await _load_user(session_factory, email)+ assert user is not None and user.tenant_id == other+ async with session_factory() as session:+ assert len((await session.execute(select(Tenant))).scalars().all()) == 1+++# ─── Re-running it ───────────────────────────────────────────────────────────+++async def test_rerunning_reports_the_account_and_changes_nothing(session_factory) -> None:+ """`make up` calls this every time, so a second run must be inert."""+ first = ba.generate_password()+ await ba.bootstrap(email=ba.DEFAULT_ADMIN_EMAIL, password=first, username="admin", reset_password=False)+ before = await _load_user(session_factory, ba.DEFAULT_ADMIN_EMAIL)+ assert before is not None+ original_hash = before.hashed_password++ _, is_new = await ba.bootstrap(+ email=ba.DEFAULT_ADMIN_EMAIL,+ password=ba.generate_password(),+ username="admin",+ reset_password=False,+ )++ assert is_new is False, "a second run reported a password it did not set"+ after = await _load_user(session_factory, ba.DEFAULT_ADMIN_EMAIL)+ assert after is not None and after.hashed_password == original_hash+ assert verify_password(first, after.hashed_password)+++async def test_a_second_run_under_a_new_address_does_not_mint_a_second_admin(+ session_factory,+) -> None:+ await ba.bootstrap(+ email=ba.DEFAULT_ADMIN_EMAIL,+ password=ba.generate_password(),+ username="admin",+ reset_password=False,+ )++ email, is_new = await ba.bootstrap(+ email="[email protected]",+ password=ba.generate_password(),+ username="admin",+ reset_password=False,+ )++ assert is_new is False+ assert email == ba.DEFAULT_ADMIN_EMAIL+ async with session_factory() as session:+ assert len((await session.execute(select(User))).scalars().all()) == 1+++async def test_an_existing_address_in_another_case_is_the_same_account(+ session_factory,+) -> None:+ """Postgres `UNIQUE` on email is case-sensitive; two rows would be two admins."""+ await ba.bootstrap(+ email=ba.DEFAULT_ADMIN_EMAIL,+ password=ba.generate_password(),+ username="admin",+ reset_password=False,+ )++ _, is_new = await ba.bootstrap(+ email=ba.DEFAULT_ADMIN_EMAIL.upper(),+ password=ba.generate_password(),+ username="admin",+ reset_password=False,+ )+ assert is_new is False+ async with session_factory() as session:+ assert len((await session.execute(select(User))).scalars().all()) == 1+++async def test_reset_password_replaces_the_credential(session_factory) -> None:+ old = ba.generate_password()+ await ba.bootstrap(email=ba.DEFAULT_ADMIN_EMAIL, password=old, username="admin", reset_password=False)++ new = ba.generate_password()+ _, is_new = await ba.bootstrap(email=ba.DEFAULT_ADMIN_EMAIL, password=new, username="admin", reset_password=True)++ assert is_new is True+ user = await _load_user(session_factory, ba.DEFAULT_ADMIN_EMAIL)+ assert user is not None+ assert verify_password(new, user.hashed_password)+ assert not verify_password(old, user.hashed_password)+++async def test_a_deactivated_orphan_does_not_block_the_first_administrator(+ session_factory,+) -> None:+ """Migration 059 deactivates the row 001 seeded; bootstrap must ignore it.++ Otherwise an upgraded deployment is told an administrator already exists,+ and the one it means is the one nobody can log into.+ """+ async with session_factory() as session:+ session.add(Tenant(id=ba.DEFAULT_TENANT_ID, name="Default", slug="default"))+ session.add(+ User(+ id=uuid.UUID("00000000-0000-0000-0000-000000000002"),+ tenant_id=ba.DEFAULT_TENANT_ID,+ email="[email protected]",+ username="admin",+ hashed_password=ORPHAN_HASH,+ role="admin",+ is_active=False,+ is_verified=True,+ )+ )+ await session.commit()++ password = ba.generate_password()+ email, is_new = await ba.bootstrap(+ email=ba.DEFAULT_ADMIN_EMAIL,+ password=password,+ username="admin",+ reset_password=False,+ )++ assert is_new is True+ assert email == ba.DEFAULT_ADMIN_EMAIL+ user = await _load_user(session_factory, ba.DEFAULT_ADMIN_EMAIL)+ assert user is not None and verify_password(password, user.hashed_password)+++# ─── How the password gets in ────────────────────────────────────────────────+++def _args(**kw) -> argparse.Namespace:+ return argparse.Namespace(password_stdin=False, **kw)+++def test_an_explicit_password_is_not_reported_as_generated(monkeypatch) -> None:+ monkeypatch.setenv("AISOC_ADMIN_PASSWORD", "a-password-the-operator-chose")+ password, generated = ba.resolve_password(_args())+ assert password == "a-password-the-operator-chose"+ assert generated is False+++def test_without_one_it_generates(monkeypatch) -> None:+ monkeypatch.delenv("AISOC_ADMIN_PASSWORD", raising=False)+ password, generated = ba.resolve_password(_args())+ assert generated is True+ assert len(password) == ba._GENERATED_PASSWORD_LENGTH+++def test_a_too_short_supplied_password_is_refused(monkeypatch) -> None:+ monkeypatch.setenv("AISOC_ADMIN_PASSWORD", "short")+ with pytest.raises(ba.BootstrapError):+ ba.resolve_password(_args())+++def test_a_supplied_password_is_never_echoed_back(capsys) -> None:+ """Only a password the operator cannot otherwise know is worth disclosing.++ Printing one they gave us puts a secret into scrollback and any CI log for+ nothing.+ """+ ba._print_credentials("[email protected]", "the-operators-own-secret", generated=False)+ out = capsys.readouterr().out+ assert "the-operators-own-secret" not in out+ assert "[email protected]" in out+++def test_a_generated_password_is_printed_because_it_exists_nowhere_else(capsys) -> None:+ password = ba.generate_password()+ ba._print_credentials("[email protected]", password, generated=True)+ out = capsys.readouterr().out+ assert password in out+ assert "not stored anywhere" in out+++def test_stdin_wins_over_the_environment(monkeypatch) -> None:+ """So a password never has to appear in shell history or `ps` output."""+ monkeypatch.setenv("AISOC_ADMIN_PASSWORD", "from-the-environment")+ monkeypatch.setattr("sys.stdin", io.StringIO("from-standard-input\n"))+ password, generated = ba.resolve_password(argparse.Namespace(password_stdin=True))+ assert password == "from-standard-input"+ assert generated is Falsediff --git a/services/api/tests/test_readme_api_docs_url.py b/services/api/tests/test_readme_api_docs_url.pyindex 5d42d209a..e781468fd 100644--- a/services/api/tests/test_readme_api_docs_url.py+++ b/services/api/tests/test_readme_api_docs_url.py@@ -17,7 +17,21 @@ import refrom app.core.config import settingsfrom app.main import create_application-README = pathlib.Path(__file__).resolve().parents[3] / "README.md"+REPO = pathlib.Path(__file__).resolve().parents[3]+README = REPO / "README.md"++# Everything else that prints this URL at a user. The README was corrected on+# its own and these were not, so `make up` went on telling every new user to+# open a 404 — the fix reached the document and not the tool.+TOOL_OUTPUT = (+ "Makefile",+ "install.sh",+ "install.ps1",+ "scripts/lab.sh",+ "docs/runbooks/LOCAL_DEVELOPMENT.md",+ "apps/docs/docs/api/rest.md",+ "apps/docs/docs/architecture/overview.md",+)def test_the_readme_points_at_the_url_the_app_mounts() -> None:@@ -34,3 +48,27 @@ def test_the_readme_points_at_the_url_the_app_mounts() -> None:assert path in {docs_url, app.openapi_url, app.redoc_url, "/health"}, (f"README advertises http://localhost:8000{path}, which the app does not serve " f"(docs are at {docs_url})")+++def test_nothing_the_tooling_prints_points_at_a_url_the_app_does_not_serve() -> None:+ """Only the interactive-docs URLs, not every route these files mention.++ `/docs`, `/redoc` and `/openapi.json` are the three that moved under+ `/api`, and the three that 404 when a file still names the old spelling.+ """+ app = create_application()+ served = {app.docs_url, app.openapi_url, app.redoc_url}+ doc_url = re.compile(r"http://localhost:8000((?:/api)?/(?:docs|redoc|openapi\.json))")++ offenders = []+ for relative in TOOL_OUTPUT:+ path = REPO / relative+ if not path.exists():+ continue+ for advertised in sorted(set(doc_url.findall(path.read_text()))):+ if advertised not in served:+ offenders.append(f"{relative}: http://localhost:8000{advertised}")++ assert not offenders, (+ "these print an API docs URL the app does not serve:\n " + "\n ".join(offenders) + f"\n(docs are mounted at {app.docs_url})"+ )diff --git a/tests/test_first_run_gate.py b/tests/test_first_run_gate.pynew file mode 100644index 000000000..23ce489c0--- /dev/null+++ b/tests/test_first_run_gate.py@@ -0,0 +1,227 @@+"""First-run defects that every test suite passed and a real deployment did not.++A live acceptance pass brought the CORE stack up from the published images,+ran the golden pipeline green, and then could not log in. Three separate+things had to be wrong at once for that to happen, and none of them was+visible to a unit test:++* migration 001 seeded `[email protected]`, an RFC 6761 special-use domain+ that `pydantic.EmailStr` rejects with a 422 before the password is compared;+* it seeded a bcrypt hash whose plaintext nobody knew, while four+ documentation pages published `changeme` for it;+* the published `aisoc-web:latest` image — the one `docker-compose.yml`+ pulls — was built with `NEXT_PUBLIC_DEMO_MODE=true`, and Next inlines that+ at build time, so a self-hoster's console called their real alerts demo+ data with no runtime way out.++Each check below is a file-content assertion because each defect lived in the+gap *between* files: a migration and a doc, a Dockerfile and a workflow. The+behavioural coverage is in `services/api/tests/test_bootstrap_admin.py`.+"""++from __future__ import annotations++import pathlib+import re++import pytest+import yaml+from email_validator import EmailNotValidError, validate_email++REPO = pathlib.Path(__file__).resolve().parents[1]+MIGRATIONS = REPO / "services/api/migrations"+WEB_DOCKERFILE = REPO / "apps/web/Dockerfile"+DEMO_AUTOLOGIN = REPO / "apps/web/src/components/demo/DemoAutoLogin.tsx"+LOGIN_PAGE = REPO / "apps/web/src/app/login/page.tsx"+ROOT_COMPOSE = REPO / "docker-compose.yml"+DEMO_COMPOSE = REPO / "infra/compose/docker-compose.demo.yml"+PUBLISH_WORKFLOW = REPO / ".github/workflows/publish-images.yml"+RELEASE_WORKFLOW = REPO / ".github/workflows/release.yml"++# The address migration 001 seeded. It may still be named in places that+# explain why it was retired; what it may not do is appear as a credential a+# reader is told to use.+RETIRED_EMAIL = "[email protected]"++# Documentation whose job is to describe the defect rather than repeat it.+HISTORY_ALLOWED = {"CHANGELOG.md"}++# The only migration permitted to name the orphaned hash, because it has to+# match that exact row to retire it. Deliberately not extended to 001: an+# exemption there would let the seed come back under a gate reporting OK,+# which is the shape of the original defect rather than a guard against it.+HASH_ALLOWED = {"059_retire_unusable_seed_admin.sql"}++SKIP_DIRS = {".git", "node_modules", ".next", "dist", "build", "plans", ".venv-firstrun"}+++def _docs() -> list[pathlib.Path]:+ out: list[pathlib.Path] = []+ for path in REPO.rglob("*.md"):+ if SKIP_DIRS & set(path.relative_to(REPO).parts):+ continue+ out.append(path)+ for path in REPO.rglob("*.mdx"):+ if SKIP_DIRS & set(path.relative_to(REPO).parts):+ continue+ out.append(path)+ return out+++# ─── The seeded credential ───────────────────────────────────────────────────+++def test_no_migration_seeds_a_login() -> None:+ """A password hash committed here is a default credential everywhere."""+ offenders = []+ for path in sorted(MIGRATIONS.glob("*.sql")):+ text = path.read_text()+ if re.search(r"INSERT\s+INTO\s+users\b", text, flags=re.IGNORECASE):+ offenders.append(f"{path.name}: INSERT INTO users")+ if path.name not in HASH_ALLOWED and re.search(r"\$2[aby]\$\d\d\$", text):+ offenders.append(f"{path.name}: bcrypt hash literal")+ assert not offenders, (+ "migrations must not ship an account:\n " + "\n ".join(offenders) + "\nThe first administrator comes from `make bootstrap`."+ )+++def test_no_page_tells_a_reader_to_sign_in_with_the_retired_address() -> None:+ offenders = [str(path.relative_to(REPO)) for path in _docs() if path.name not in HISTORY_ALLOWED and RETIRED_EMAIL in path.read_text()]+ assert not offenders, (+ f"{RETIRED_EMAIL} is published as a credential in:\n "+ + "\n ".join(offenders)+ + f"\nThe login route rejects {RETIRED_EMAIL} with a 422 — it is not a password problem, "+ "and a doc that merely agrees with the old seed is not fixed."+ )++[email protected]("doc", _docs(), ids=lambda p: str(p.relative_to(REPO)))+def test_every_documented_login_uses_an_address_the_api_accepts(doc: pathlib.Path) -> None:+ """Run the validator the route runs, not a copy of its reserved-domain list.++ `"email":"[email protected]"` was copied into four pages. Each was+ self-consistent with the seed and every one of them was unusable.+ """+ text = doc.read_text()+ addresses = re.findall(r'"email"\s*:\s*\\?"([^"\\]+)\\?"', text)+ for address in addresses:+ if address.startswith("$") or address.startswith("<"):+ continue # a placeholder for the reader to substitute+ try:+ validate_email(address, check_deliverability=False)+ except EmailNotValidError as exc:+ pytest.fail(+ f"{doc.relative_to(REPO)} documents a login as {address!r}, which "+ f"POST /api/v1/auth/login rejects with a 422 before checking the "+ f"password: {exc}"+ )+++# ─── The published image ─────────────────────────────────────────────────────+++def test_the_web_dockerfile_defaults_ship_no_demo_credential() -> None:+ """Next inlines NEXT_PUBLIC_* wherever referenced, default or not."""+ for line in WEB_DOCKERFILE.read_text().splitlines():+ match = re.match(r"\s*ARG\s+(NEXT_PUBLIC_DEMO_AUTOLOGIN_\w+)=(.*)$", line)+ if not match:+ continue+ value = match.group(2).strip().strip('"').strip("'")+ assert value == "", (+ f"{match.group(1)} defaults to {value!r}. Every build made without an explicit "+ "value — including a self-host build — would inline that into the client bundle."+ )+++ "source", [DEMO_AUTOLOGIN, LOGIN_PAGE], ids=lambda p: p.name+)+def test_no_client_component_hardcodes_a_demo_credential(source: pathlib.Path) -> None:+ """Gating the render hides the panel; it does not remove the strings.++ Both of these declared `const DEMO_EMAIL = '…'` at module scope, so the+ pair was inlined into every bundle the project builds — the login page's+ even though the panel that shows it is already behind `isDemoMode()`.+ """+ text = source.read_text()+ for name in ("DEMO_EMAIL", "DEMO_PASSWORD"):+ literal = re.search(rf"const\s+{name}\s*(?::[^=]+)?=\s*['\"]([^'\"]+)['\"]", text)+ assert literal is None, (+ f"{source.name} assigns {name} the literal {literal.group(1)!r}. Read it from "+ "process.env.NEXT_PUBLIC_DEMO_AUTOLOGIN_* so only a demo build carries it."+ )+ fallback = re.search(+ rf"process\.env\.NEXT_PUBLIC_DEMO_AUTOLOGIN_\w+[^;]*\|\|\s*['\"]([^'\"]+)['\"]",+ text,+ )+ assert fallback is None, (+ f"{source.name} falls back to the literal {fallback.group(1)!r}. A fallback is "+ "inlined into every build, demo or not."+ )+++def _matrix(workflow: pathlib.Path, job: str) -> list[dict]:+ spec = yaml.safe_load(workflow.read_text())+ return spec["jobs"][job]["strategy"]["matrix"]["include"]+++def _demo_build_step(workflow: pathlib.Path, job: str) -> dict:+ spec = yaml.safe_load(workflow.read_text())+ for step in spec["jobs"][job]["steps"]:+ if "NEXT_PUBLIC_DEMO_MODE=true" in str(step.get("run", "")):+ return step+ raise AssertionError(f"{workflow.name}: no step sets NEXT_PUBLIC_DEMO_MODE")+++ ("workflow", "job"),+ [(PUBLISH_WORKFLOW, "build"), (RELEASE_WORKFLOW, "docker-push")],+ ids=["publish-images", "release"],+)+def test_the_demo_bundle_is_built_by_its_own_matrix_entry(workflow: pathlib.Path, job: str) -> None:+ """The demo build must be a separate image, not a flag on the product one.++ It was a flag on the product one, which is how `latest` — what `make up`+ pulls — came to carry a bundle that disabled every write control.+ """+ demo_entries = [e for e in _matrix(workflow, job) if str(e.get("demo", "")) == "true"]+ assert len(demo_entries) == 1, f"{workflow.name}: expected exactly one matrix entry with `demo: 'true'`, " f"found {len(demo_entries)}"+ assert demo_entries[0]["image"].endswith("aisoc-web")++ step = _demo_build_step(workflow, job)+ assert "matrix.demo" in str(step.get("if", "")), (+ f"{workflow.name}: the demo build args are not gated on `matrix.demo`, so a "+ f"product build can still receive them (if: {step.get('if')!r})"+ )+++def test_publish_images_keeps_demo_off_the_moving_tags() -> None:+ text = PUBLISH_WORKFLOW.read_text()+ for tag in ("value=main", "value=latest"):+ line = next(ln for ln in text.splitlines() if tag in ln and "type=raw" in ln)+ assert "matrix.demo != 'true'" in line, f"publish-images.yml publishes `{tag}` without excluding the demo build: {line.strip()}"+++def test_release_publishes_the_demo_under_its_own_tag() -> None:+ text = RELEASE_WORKFLOW.read_text()+ assert "-demo" in text, "release.yml has no demo-suffixed tag for the demo build"+ assert 'matrix.demo }}" = "true"' in text, (+ "release.yml does not branch its tag list on `matrix.demo`, so `vX.Y.Z` and " "`latest` could carry the demo bundle again"+ )+++def test_each_compose_file_pulls_the_image_built_for_it() -> None:+ root = ROOT_COMPOSE.read_text()+ demo = DEMO_COMPOSE.read_text()++ root_ref = re.search(r"image:\s*(ghcr\.io/beenuar/aisoc-web:\S+)", root)+ demo_ref = re.search(r"image:\s*(ghcr\.io/beenuar/aisoc-web:\S+)", demo)+ assert root_ref and demo_ref++ assert "demo" not in root_ref.group(1), (+ f"docker-compose.yml (what `make up` starts) pulls {root_ref.group(1)} — " "a self-host stack must not pull a demo bundle"+ )+ assert "demo" in demo_ref.group(1), (+ f"the demo stack pulls {demo_ref.group(1)}, which is the product build: no banner, "+ "no auto-login, and a visitor bounced to /login"+ )