cortex-viz

There is a single supported line and a documented upgrade path, which is what this criterion asks of a project this size. Upgrading means reinstalling the plugin (or pip install -e . from a clone); no configuration migration has ever been required, and no interface removal has occurred across the 2.x series. Breaking changes and their migration steps are recorded per version in https://github.com/cdeust/cortex-viz/blob/main/CHANGELOG.md. Older versions are not backported: users move to the newest, which is stated rather than implied.

GitHub Issues is used for bug tracking and for enhancement requests, publicly and searchably, with every issue in the last six months resolved and closed. https://github.com/cdeust/cortex-viz/issues

SECURITY.md, 'Credit': reporters are credited by name in the security advisory and the release notes unless they ask not to be, and are invited to state in the report which name or handle they want used or that they prefer to remain anonymous. https://github.com/cdeust/cortex-viz/blob/main/SECURITY.md

SECURITY.md, 'What happens next', publishes the process and its timelines: acknowledgement within 14 days, assessment of severity and affected versions within 30 days of acknowledgement, fix or a written dated plan tracked in the advisory, public disclosure after the fix ships, with an email escalation path if 14 days pass unanswered. The scope of what is and is not covered is stated in the same file. https://github.com/cdeust/cortex-viz/blob/main/SECURITY.md

CONTRIBUTING.md names the style guide per primary language and the tool for each: PEP 8 for Python with the project's [tool.ruff] configuration in pyproject.toml, and for the browser UI vanilla ESM and IIFE with no bundler or framework, matching the file being edited. It also states the structural limits that review enforces (500-line file, 50-line function, 4 parameters, 3 nesting levels), which are the standard behind issues #17, #23, and #41. https://github.com/cdeust/cortex-viz/blob/main/CONTRIBUTING.md#coding-style

Both languages are automatically enforced by required CI jobs. Python: lint runs ruff check (rule set in [tool.ruff.lint].select) plus ruff format --check; ruff is pinned in the dev extra (>=0.15.0,<0.16.0) and installed from uv.lock, so CI runs the same version a contributor does. JavaScript: js-lint runs npm run lint (ESLint 10 flat config, eslint.config.mjs) over ui/, with a rule set scoped to what a reader cannot catch in one file — no-undef, no-implicit-globals, no-redeclare, no-unused-vars and the always-a-bug rules — since the UI is vanilla script-tag JavaScript with hand-maintained load order and no bundler. Vendored minified bundles under ui/**/vendor/ are excluded. Wiring it found and fixed three variables (domainsSeen, globalCount, hotCount in ui/unified/js/knowledge.js) that were assigned without declaration and so leaked onto window. Closed by https://github.com/cdeust/cortex-viz/issues/45

There is no make or configure build to pass variables to. The build is PEP 517 via hatchling, driven by pyproject.toml, where the equivalent settings are declarative rather than variable-driven, and the browser UI ships as static assets with no build step at all.

Nothing is compiled, so there is no debug-information or symbol-stripping step to preserve. Python source ships as source in the wheel and the UI ships unminified and unbundled, which means the shipped JavaScript is already the readable original.

There is no recursive make. The build is a single PEP 517 hatchling invocation.

This is the disposition the criterion prescribes for scripting languages where the source is used directly rather than compiled. Python source and the static UI tree are shipped and executed as-is. The integrity property this criterion protects is provided by different means here and is verifiable: a sha256sum manifest over the whole ui/ tree, per-asset checksums, and a Sigstore build-provenance attestation binding every artifact digest to this repository, workflow, and commit.

The standard mechanism for this product's ecosystem: the Claude Code plugin marketplace (claude plugin marketplace add cdeust/Cortex then claude plugin install cortex-viz), which is how a plugin is normally installed. For non-plugin use it is a standard PEP 517 package: pip install -e . from a clone, and it registers in any MCP host as a plain stdio process. https://github.com/cdeust/cortex-viz/blob/main/README.md#install

There is no bespoke installer with prefix or destination variables. Installation is delegated to pip and to the plugin host, both of which honour their own standard location and environment conventions.

git clone, pip install -e ".[dev]", python -m pytest gets a working development environment, and npm ci && npm test the browser half. Critically, no external infrastructure is needed to run it: CORTEX_VIZ_NO_DB=1 python3 -m cortex_viz starts the server with no Cortex install and no PostgreSQL, serving the Trace view from ~/.claude session files alone. https://github.com/cdeust/cortex-viz/blob/main/CONTRIBUTING.md#running-the-suites

Computer-processable and complete on both halves. Python: pyproject.toml declares runtime dependencies and the viz-tile, community, data, and dev extras, with uv.lock pinning the resolved graph; every release additionally ships a CycloneDX SBOM (cortex-viz.cdx.json) generated from that lock. JavaScript: package.json plus package-lock.json, devDependencies only, since the harness ships nothing. https://github.com/cdeust/cortex-viz/blob/main/pyproject.toml

Two independent mechanisms. Dependabot covers all three dependency surfaces weekly (pip, npm, and github-actions, the last so SHA-pinned actions still receive security updates): https://github.com/cdeust/cortex-viz/blob/main/.github/dependabot.yml. OpenSSF Scorecard grades dependency posture weekly: https://github.com/cdeust/cortex-viz/blob/main/.github/workflows/scorecard.yml. Stated honestly, this is new: nothing was watching before, which is exactly why 19 npm advisories in the test harness had gone unnoticed until a manual audit on 2026-07-28 (https://github.com/cdeust/cortex-viz/issues/49).

Reused components are standard registry packages with no forked or vendored convenience copies to diverge: Python via pip and pyproject.toml, JavaScript devDependencies via npm, GitHub Actions SHA-pinned with the version in a trailing comment so Dependabot rewrites pin and comment together. The ui/ tree is first-party source, not a vendored third party. One qualifier, recorded rather than omitted: four UI pages load three.js and 3d-force-graph from the unpkg CDN. Those are version-pinned in the script tag, so identifying and updating them is trivial, but they carry no Subresource Integrity hash and are outside the release fingerprint; https://github.com/cdeust/cortex-viz/issues/50 proposes vendoring them, which would also close that gap.

The documented interface matches the shipped one. Both MCP tools (open_visualization with its view parameter, get_methodology_graph) are documented in the README as implemented, and the data sources behind the HTTP surface are tabulated in docs/ARCHITECTURE.md against the current code. CONTRIBUTING.md requires an interface change to update the README in the same pull request.

CI runs on every push and every pull request, exercising the assembled system rather than isolated units: 431 pytest tests including HTTP endpoint and server-integration suites, and 175 vitest tests that load the real ui/ source files into jsdom and assert cross-module behaviour such as SVG-versus-canvas renderer agreement on one model. Both jobs are required and both report pass or fail per run. https://github.com/cdeust/cortex-viz/blob/main/.github/workflows/ci.yml

The practice holds for defects in code that the suites can reach. #35's fix to the DB-skip fixture, which had silently become a no-op because MemoryReader was lazy, shipped with the corrected assertion; #36 landed its verdict logic as a pure seam with every emission asserted, including the quiet complete state, and gated by Stryker rather than by line coverage. Two of the last six months' fixes carry no test and the reason is stated rather than hidden: #31 was user-visible copy (em-dash removal) and #39 was a CI workflow fix whose failure mode was startup_failure on main, verified by workflow_dispatch post-merge because a push-and-schedule-only workflow is invisible to pull-request CI. Neither is testable by the pytest or vitest suites. The rule is now written down rather than customary: CONTRIBUTING.md requires a regression test that fails on the pre-fix code. https://github.com/cdeust/cortex-viz/blob/main/CONTRIBUTING.md

Measured on merged main commit 3a11c6653c1aea74c7b57409c6e762bcd6e9993f. The required CI job runs coverage run -m pytest followed by coverage report; pyproject.toml enforces fail_under = 80, so a regression fails the pull request. The complete local validation reported 988 passed, 10 skipped and 81% Python statement coverage (11,674 statements, 2,272 missed); the post-merge CI run passed. The browser surface is separately gated by 259 JavaScript tests. Evidence: https://github.com/cdeust/cortex-viz/pull/97 and https://github.com/cdeust/cortex-viz/actions/runs/30837051506

CONTRIBUTING.md states it as a requirement in the imperative, not as encouragement: 'As major new functionality is added, tests for that functionality MUST be added to the automated test suite in the same pull request', followed by 'a pull request that adds behaviour without tests will be sent back', and separately that a bug fix requires a regression test failing on the pre-fix code. https://github.com/cdeust/cortex-viz/blob/main/CONTRIBUTING.md#tests-are-mandatory-for-new-functionality

The requirement, the command for each suite, and the standard tests are judged by are all in CONTRIBUTING.md, including that strength is measured by mutation rather than line coverage, with the Stryker configuration in stryker.conf.json and surviving mutants triaged in tests/js/MUTATION_NOTES.md. https://github.com/cdeust/cortex-viz/blob/main/CONTRIBUTING.md

Maximally strict where practical, enforced by a required CI job. The lint job in .github/workflows/ci.yml runs ruff check and ruff format --check over the whole tree on every push and pull request; js-lint runs ESLint over ui/. The Python rule set is wider than ruff's default: [tool.ruff.lint].select is E, W, F, I, N, UP, B, C4, SIM, RUF (pyproject.toml). --select ALL is deliberately NOT the target — it reports 6,369 findings here, dominated by docstring-style (D), annotation-completeness (ANN) and assert-in-test (S101) rules that would be answered with a blanket ignore, which is a preference dressed as a gate. Two rules are ignored with the reason written at the ignore: RUF100, because under a curated select it deletes suppressions for rules the set does not enable (it removed 52 of the 60 it flagged, incl. 4 security ones), and SIM105, because ruff's own fixer withholds it at all 42 sites here — every one carries the named failure mode as a comment, which the rewrite would erase. Note on the earlier figure: the 486 violations cited before were measured with ruff's PREVIEW rules enabled, not the defaults; on stable rules the tree passed then and now. The real gate cost was 386 findings under the widened set, all cleared. Closed by https://github.com/cdeust/cortex-viz/issues/45

The principles are applied concretely and the instances are auditable. Least privilege: Cortex's memory tables are never written and the ban on import mcp_server.* keeps the separation structural; workflow tokens are permissions: read-all by default and widened per job only where a job must write. Fail-safe defaults: binds 127.0.0.1 and never 0.0.0.0, an unreachable database degrades to a named no-DB mode rather than erroring or inventing data, and an unknown static path returns 403 or 404 rather than guessing. Complete mediation: Host, Origin, and same-origin checks run per request in the handler path, not once at startup. Defence in depth: three independent controls on the browser-to-server boundary with distinct failure modes, so a cross-site write requires two of them to fail. Economy of mechanism: no bundler, no framework, no plugin system, no authentication subsystem. Set out with the per-boundary argument in https://github.com/cdeust/cortex-viz/blob/main/docs/ASSURANCE_CASE.md

cortex-viz implements no cryptography. It stores no passwords, mints no keys, tokens, or nonces, and runs no cryptographic protocol: it is a local read-mostly visualization server bound to 127.0.0.1. Release signing is delegated entirely to Sigstore via GitHub's attest-build-provenance action, so no signing key is handled by this project's code.

cortex-viz implements no cryptography. It stores no passwords, mints no keys, tokens, or nonces, and runs no cryptographic protocol: it is a local read-mostly visualization server bound to 127.0.0.1. Release signing is delegated entirely to Sigstore via GitHub's attest-build-provenance action, so no signing key is handled by this project's code.

The one credential-bearing value cortex-viz handles is DATABASE_URL, which may embed a database password. It is supplied entirely as external configuration, either the plugin's database_url user setting or the DATABASE_URL environment variable, is never written into a configuration file the project ships, never committed, and never logged. Changing or rotating it requires no code change, no rebuild, and no reinstall: set the value and restart the server. The project stores no other credential and no private key of its own.

The project implements no TLS and terminates no TLS connection: the server is plain HTTP on loopback. The one HTTPS request in the product is the browser's own fetch of a CDN library, where protocol version selection belongs to the browser and to unpkg, not to this software.

The software does not use TLS itself, so there is no certificate for it to verify. The CDN subresource fetch is performed by the browser, which verifies the certificate under its own policy.

The software does not use TLS, and sends no private information over one. It has no cookies, no sessions, no tokens, and no authentication headers of any kind.

Release v2.8.0 was produced by the committed Release.yaml workflow and publishes a wheel, source archive, CycloneDX SBOM, UI fingerprint manifest, and SHA-256 companions. The workflow uses GitHub OIDC with actions/attest-build-provenance, so the signing identity is short-lived and no project private key exists on the distribution site. On 2026-08-03 all four primary assets passed their checksums and gh attestation verify <file> --repo cdeust/cortex-viz, which verifies the Sigstore certificate and transparency-log provenance. Release: https://github.com/cdeust/cortex-viz/releases/tag/v2.8.0. Verification process: https://github.com/cdeust/cortex-viz/blob/main/SECURITY.md and https://github.com/cdeust/cortex-viz/blob/main/.github/workflows/Release.yaml

Untrusted input is checked against allowlists and rejected, not sanitized-and-hoped. The request-header surface is allowlisted in cortex_viz/server/http_security.py: validate_host_header requires the Host header to name a loopback host from a fixed frozenset (DNS-rebinding defense, CWE-346/350), resolve_allowed_origin allowlists origins (CWE-942), _is_safe_header_value rejects any character below 0x20 plus 0x7f before a request-derived value is reflected into a response header (CWE-113, which Python's send_header does not filter), and enforce_same_origin_write gates writes (CWE-352). The request-path surface is validated before the filesystem is touched: reject empty, NUL-bearing, .., and dot-prefixed components, then resolve() and require containment within the base directory and that the target is an existing file, returning 403 or 404 rather than a guess. The qualifier, stated rather than omitted: CodeQL still reports 10 py/path-injection alerts across four files, of which only the static-serving sites have been read in detail; the site-by-site triage with a traversal regression test per site is https://github.com/cdeust/cortex-viz/issues/46.

docs/ASSURANCE_CASE.md contains all four required elements. Threat model: six numbered adversaries with their reach and STRIDE categories, plus an explicit out-of-scope statement. Trust boundaries: four, identified and ordered by exposure. Secure design principles: a table of seven principles each with its concrete instance in this codebase. Common implementation weaknesses: a table of twelve weakness classes with the status of each. It also states where the argument is incomplete (the untriaged findings on the untrusted-data boundary) and what it does not cover, rather than presenting itself as finished. https://github.com/cdeust/cortex-viz/blob/main/docs/ASSURANCE_CASE.md

The security-and-quality suite includes CodeQL's security queries for both languages, which is how the current py/path-injection, js/remote-property-injection, and js/incomplete-html-attribute-sanitization alerts were surfaced at all.

No memory-unsafe language is used. The project is Python and browser JavaScript only; there is no C, C++, or unsafe Rust anywhere in the tree, and no compiled extension is authored by this project.