Skip to content

armgit / AiSOC

Public Imported from GitHub
0

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.

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.yml
index 66e796b2a..9a81bac37 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -358,6 +358,16 @@ jobs:
run: |
python3 -m pip install --quiet pytest
python3 -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.yml
index 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 stack
run: ./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 end
run: python3 tests/e2e/golden_pipeline/run_golden_pipeline.py
diff --git a/.github/workflows/publish-images.yml b/.github/workflows/publish-images.yml
index 1a1eaa72e..a6f62ad65 100644
--- a/.github/workflows/publish-images.yml
+++ b/.github/workflows/publish-images.yml
@@ -56,6 +56,25 @@ jobs:
dockerfile: apps/web/Dockerfile
image: 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 # v6
with:
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.yml
index 2143505ca..273a36d2f 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -119,6 +119,17 @@ jobs:
dockerfile: apps/web/Dockerfile
image: 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: build
uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
with:
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.md
index 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 not
perform.** `capture_forensics` was an `ActionType` with no executor
anywhere, and `services/agents/app/agents/investigation_agent.py` proposes
diff --git a/Makefile b/Makefile
index 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-script
help:
@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.md
index cced87168..9fcd7af49 100644
--- a/README.md
+++ b/README.md
@@ -40,9 +40,15 @@ recorded, and proposes an action. A human approves before anything executes.
```bash
git clone https://github.com/beenuar/AiSOC && cd AiSOC
+cp .env.example .env
make 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 to
run next. Requires Docker with ~6 GB of RAM.
diff --git a/apps/docs/docs/api/rest.md b/apps/docs/docs/api/rest.md
index 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 token
curl -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 token
curl 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 p
When 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.md
index 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 stops
diff --git a/apps/docs/docs/deployment/docker.md b/apps/docs/docs/deployment/docker.md
index 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 provenance
Each image is signed with [Cosign](https://docs.sigstore.dev/cosign/overview/)
diff --git a/apps/docs/docs/quickstart.md b/apps/docs/docs/quickstart.md
index 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 UI
Visit [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) — install
diff --git a/apps/web/Dockerfile b/apps/web/Dockerfile
index 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.tsx
index 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>
<button
diff --git a/apps/web/src/components/demo/DemoAutoLogin.tsx b/apps/web/src/components/demo/DemoAutoLogin.tsx
index 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.yml
index 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.md
index 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 au
All 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.md
index 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 (forward
poetry 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 Kafka
docker exec -i aisoc-kafka kafka-console-producer \
diff --git a/infra/compose/docker-compose.demo.yml b/infra/compose/docker-compose.demo.yml
index 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 then
diff --git a/install.ps1 b/install.ps1
index 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 DarkGray
diff --git a/install.sh b/install.sh
index 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 each
make smoke # re-run the end-to-end pipeline check
diff --git a/scripts/doctor.sh b/scripts/doctor.sh
index 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 pipefail
PROFILE_FULL=0
QUIET=0
+PORTS_ONLY=0
for arg in "$@"; do
case "$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 @@ else
pass "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 0
fi
+ 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"
fi
done
+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.sh
index 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.py
new file mode 100644
index 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.sql
index 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',
- '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.sql
new file mode 100644
index 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.py
new file mode 100644
index 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(
+ 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,
+ 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 False
diff --git a/services/api/tests/test_readme_api_docs_url.py b/services/api/tests/test_readme_api_docs_url.py
index 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 re
from app.core.config import settings
from 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.py
new file mode 100644
index 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"
+ )