OSPMAE encodes open-source projects, architectures, frameworks, standards, capabilities and their evidence requirements in machine-readable and visual forms. A project maintainer maps a release once; any adopter (or ecosystem operator) reads that mapping each time from the machine-readable record. The Grype/Syft dependency pipeline turns a project's repositories into a live source of vulnerability findings for the whole catalogue, and each release keeps an exportable record of what it contains.
Applications in the same family share a design system and conventions: KEEN (adopter-side assurance), OSPMAE (adoption readiness, this repository), and the mosp-design-system shared UI foundation.
- Projects and versions - a catalogue of open-source projects with releases, drafts, subscriptions, changelog records and exportable manifests. Owners and owner groups manage their own projects; the catalogue is the common meeting point between project capabilities and adopter needs. A project can track one branch of its repository in place of releases: the branch head is re-cloned and scanned on an interval the owner chooses, once an hour at most. A project following a release feed stages each new release as a draft for its owners to publish, or publishes new releases as they arrive when the owner switches that on; the version that becomes Latest is scanned either way.
- Frameworks and capability mapping - architecture frameworks (Universal Wallet Reference Architecture by default) encoded as machine-readable trees with per-node capability definitions, project-to-framework mappings and D3 visualisations.
- Dependency scanning - an operator-configured Grype/Syft pipeline clones policy-permitted repositories (host allowlist, command allowlists, fixed scrubbed environment), parses lockfiles/SBOMs and records dependencies, vulnerabilities and remediation status against each version.
- Comparisons - side-by-side project/version diffs with capability matrices and dependency/vulnerability deltas, plus CSV/XLSX/PDF exports served as neutral attachments.
- Questions and notifications - account-threaded questions on project versions with role-based answer permissions, e-mail notifications, and realtime browser notification over a bounded WebSocket channel.
- Organisations and dashboards - organisations are first-class records that projects belong to (created from the free-text name on first use), with admin-managed user/group membership, a global dependency dashboard with per-project unfixed-finding summaries and organisation filters, and a searchable dependency browser keyed by UUID.
- E-mail delivery - outgoing mail is a transactional outbox: senders queue inside their own transaction and a worker delivers with exponential backoff, recording each attempt so a broken SMTP configuration is visible in the admin's E-mail outbox view (and users can see their own delivery history under Account).
- Authentication - local accounts (PBKDF2/600k, with KEEN's rules for new passwords) with a second factor (TOTP authenticator apps, WebAuthn security keys/passkeys and single-use recovery codes), OpenID Connect with per-provider configuration, optional trusted header identity from an authenticating proxy, database-backed sessions with rolling and absolute lifetimes, and CSRF-protected unsafe writes. The second factor applies to local sign-in under the
OSPMAE_MFA_POLICYsetting (optional,admins, orall); an account's enrolment change invalidates its existing local sessions, a five-minute browser ceremony runs outside the session cookie, and WebAuthn requires an HTTPSOSPMAE_PUBLIC_BASE_URL.
Administrators switch optional product areas on and off on the Administration page (Features tab, /admin.html#features); a switched-off area answers 404, disappears from the UI and skips its background work, and its records are kept. Each save is checked against the configuration revision it started from, and every revision is kept. The deployment's .env switches (OSPMAE_FEATURE_*, all default true) are a ceiling: an area turned off there stays off and its switch on the page cannot turn it on.
| Switch | What it toggles |
|---|---|
OSPMAE_FEATURE_FRAMEWORKS |
framework management, capability trees, UWRA seeding |
OSPMAE_FEATURE_MANIFESTS |
manifest editing, sharing and export |
OSPMAE_FEATURE_QUESTIONS |
question threads, notifications bell |
OSPMAE_FEATURE_DEPENDENCY_SCANS |
Grype/Syft discovery, dependency dashboard, release feeds, tracked-branch re-scans |
OSPMAE_FEATURE_COMPARISONS |
the project compare endpoint |
OSPMAE_FEATURE_RELEASE_FEED |
RSS/Atom release polling |
Authentication, projects, administration and the unified dependency/vulnerability dashboard stay available in every configuration.
cp .env.example .env # then edit the required values
docker compose up --build.env.example documents every setting and ships every credential empty. Set the :?-guarded values (POSTGRES_PASSWORD and REDIS_PASSWORD, for example each from openssl rand -hex 32) before the first docker compose up; compose refuses to start a deployment with either one missing.
The services:
component-ui- nginx serving the built UI, proxying/v1/and/ws/to the API, adding the security headers and cache policy fromservices/ui/nginx/default.conf.component-api- the FastAPI application (uvicorn) alongside Celery workers and a beat scheduler.postgres/valkey- catalogue storage and the Celery broker.
Third-party container images are pinned by digest; tools/docker_image_pins.py check verifies that every tracked tag still resolves to its pinned digest, and the nightly workflow opens review when an upstream tag moves (see .github/workflows/docker-image-pins.yml).
Run the following to create the initial (admin) user. It asks for the password, so none is written into the command or the shell history; choose one of 15 characters or more that is hard to guess (the rules are in SECURITY.md):
docker compose exec component-api python -c '
import getpass
from app.db.session import SessionLocal
from app.security.auth import create_user
db = SessionLocal()
try:
create_user(
db,
username="admin", # 1-64 chars: letters, digits, _ - .
password=getpass.getpass("Password for the first administrator: "),
email="admin@example.com", # optional: account and security mail
role="admin",
)
finally:
db.close()
'When a local account has lost its authenticators and recovery codes, an operator removes them so the owner can sign in with the password and enrol again; the account's local sessions end and the owner is mailed a security notice:
docker compose exec component-api python scripts/mfa_admin.py USERNAME --reset --confirm-username USERNAME| Setting | Purpose |
|---|---|
OSPMAE_PUBLIC_BASE_URL |
The origin used in links printed into e-mail (SSO email address verification, which needs HTTPS). Set this before enabling mail flows. |
OSPMAE_FEATURE_* |
Installation switches above. |
OSPMAE_LOCAL_AUTH_ENABLED |
Local password sign-in. Administrators create accounts, set their e-mail and reset passwords; single sign-on reaches existing accounts only. |
OSPMAE_MFA_POLICY, OSPMAE_MFA_ENCRYPTION_KEY |
Local second factor: optional (default), admins or all accounts must complete TOTP/security-key/recovery-code verification on local sign-in; the key is a persistent Fernet key (openssl rand -base64 32) that encrypts TOTP secrets at rest and belongs in your secrets manager. |
OSPMAE_OIDC_* (or OSPMAE_GITHUB_*) |
SSO providers; each enabled provider requires explicit CLIENT_ID, CLIENT_SECRET, endpoints and REDIRECT_URI. |
OSPMAE_TRUST_REMOTE_USER + OSPMAE_REMOTE_USER_HEADER_NAME + OSPMAE_REMOTE_USER_TRUSTED_CIDRS |
Trusted header identity for deployments where the network path alone reaches the API through the authenticating proxy. The header is believed only from the proxies named in OSPMAE_REMOTE_USER_TRUSTED_CIDRS, which is required in this mode. |
OSPMAE_PASSWORD_MIN_LENGTH |
Characters a new local password needs: 15 by default; 8 to 14 only with OSPMAE_MFA_POLICY=all. |
OSPMAE_TRUSTED_PROXY_CIDRS |
Networks whose hosts may form the trusted side of a forwarded client address chain (rate limits, audit records). A proxy in front of OSPMAE must append the connecting client's address to X-Forwarded-For, or overwrite the header. |
Project project_type |
Not a setting: it is a server-controlled vocabulary (ledger, identity, wallet, credentials, interoperability, privacy, cryptography, governance, tooling, library, application, service, other); free-text values are refused at intake. |
| Framework-gated fields | The capability/profiles/protocols/keys/algorithms fields describe the Universal Wallet Reference Architecture. They are presented only in the framework-options wizard step; with OSPMAE_FEATURE_FRAMEWORKS=false the step is removed and blank values save, so nothing leaks into a framework-free deployment. |
OSPMAE_DEPENDENCY_DISCOVERY_*, OSPMAE_SYFT_*, OSPMAE_GRYPE_* |
Scan pipeline policy (host allowlist, time/memory budgets, scanner paths). |
OSPMAE_SMTP_* |
Outgoing mail. |
# API tests, lint, types (Poetry env)
cd services/api
poetry install --with dev --no-root
poetry run bash ../../tests.sh # needs OSPMAE_TEST_DATABASE_URL
# UI tests and formatting
npm ci --prefix services/ui/tests
bash tests-ui.sh
bash format-ui.sh --checktests.sh runs the whole CI surface locally: backend pytest with branch coverage against a disposable PostgreSQL database named by OSPMAE_TEST_DATABASE_URL (the suite runs on PostgreSQL only, and empties the database it is given), the no-skips guard, UI tests under c8, and syntax checks across first-party JavaScript. .github/workflows/tests.yml runs the same steps on every push. Documentation for development conventions lives in AGENTS.md; the deployment security model lives in SECURITY.md.
services/api/ FastAPI application, Alembic migrations, tasks, tests
services/ui/ nginx + first-party pages, build tooling, tests
services/api/alembic/ Migrations (through 0040_session_digests)
tools/ docker-image-pins
.github/workflows/ CI (tests, docker-image-pins)
See LICENSE and the bundled design-system licence (services/ui/public/vendor/mosp-design-system/LICENSE after a build).