PerspectiveGraph

Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

The repository contains the full development history, not release snapshots: 136 commits on main, of which only 14 are the automated release commits - so 122 are interim work available for review between releases. Changes land through pull requests that run the full CI suite (build, vet, tests, race detector, staticcheck, gosec, govulncheck, CodeQL, Trivy, fuzzing and an 80% coverage gate) before merge.

https://github.com/luiacuaniello/perspectivegraph/commits/main
https://github.com/luiacuaniello/perspectivegraph/pulls?q=is%3Apr+is%3Aclosed

Repository on GitHub, which uses git. git is distributed.

Every release has a unique version identifier. 16 git tags, all of the form vX.Y.Z, with no duplicates. Versions are produced by release-please from Conventional Commits, so a version is never reused or hand-assigned, and the same identifier appears on the git tag, the GitHub release, the release binaries, the container image tags on GHCR, and the version markers in the README.

https://github.com/luiacuaniello/perspectivegraph/tags

Every release is identified in version control by a git tag of the form vX.Y.Z, created automatically by release-please when the release pull request is merged. 16 tags to date, matching the 15 published GitHub releases one to one.

https://github.com/luiacuaniello/perspectivegraph/tags

Non-trivial release notes file in repository: https://github.com/luiacuaniello/perspectivegraph/blob/main/CHANGELOG.md.

N/A: no publicly known vulnerability with a CVE assignment has ever affected this project's own code. Every release carries generated release notes (release-please, from Conventional Commits) and a CHANGELOG entry, so the mechanism to record such a fix exists and will be used if one is ever assigned. Security reporting goes through a private channel documented in SECURITY.md, and no advisory has been published against the repository.

https://github.com/luiacuaniello/perspectivegraph/releases
https://github.com/luiacuaniello/perspectivegraph/security/advisories

Non-trivial SECURITY[.md] file found file in repository: https://github.com/luiacuaniello/perspectivegraph/blob/main/SECURITY.md. [osps_do_02_01]

GitHub Issues is enabled and is the tracker for individual issues, with labels used to mark entry points for new contributors ("good first issue"). Pull requests are tracked in the same place and every one runs the full CI suite before merge.

https://github.com/luiacuaniello/perspectivegraph/issues

No bug report has been submitted by anyone other than the maintainer in the period. The five open issues were all opened by the maintainer as scoped tasks for new contributors, so there is no backlog of unacknowledged external reports. The project went public very recently; the tracker is open and monitored.

Same situation as bug reports: no enhancement request has been submitted by a third party in the period. Planned work is tracked publicly in ROADMAP.md, which states explicitly what is done, what is scaffolded and what has not been started, so the direction is reviewable before anyone asks.

https://github.com/luiacuaniello/perspectivegraph/issues
https://github.com/luiacuaniello/perspectivegraph/blob/main/ROADMAP.md

GitHub Issues is the public, searchable archive of reports and responses; it is open to anyone without an account for reading, and every issue keeps its full comment history. Pull request discussions are archived in the same place, and each release links the commits it contains.

https://github.com/luiacuaniello/perspectivegraph/issues?q=is%3Aissue

SECURITY.md publishes the process: how to report, what to include, what happens next, and what is in and out of scope. It states the preferred private channel and a fallback if private reporting is unavailable, and describes how the reporter is credited in the advisory and release notes unless they prefer anonymity. It is linked from the README and surfaced by GitHub in the repository's Security tab.

https://github.com/luiacuaniello/perspectivegraph/blob/main/SECURITY.md

Private reporting is supported and is the preferred route. GitHub private vulnerability reporting is enabled on the repository (verified: the API reports "enabled": true), so a reporter uses Security → Report a vulnerability and the report stays private to the maintainers until a fix is published. SECURITY.md documents this as the first option, with a fallback for cases where it is unavailable: open a minimal public issue containing no details, asking only for a private contact.

https://github.com/luiacuaniello/perspectivegraph/blob/main/SECURITY.md

N/A: no vulnerability report has been received. The repository has no published or draft security advisories, and no third party has opened an issue. The reporting channel is documented and live (GitHub private vulnerability reporting is enabled on the repository), so reports have somewhere to arrive; none have.

https://github.com/luiacuaniello/perspectivegraph/security/advisories

Non-trivial build file in repository: https://github.com/luiacuaniello/perspectivegraph/blob/main/Makefile.

Non-trivial build file in repository: https://github.com/luiacuaniello/perspectivegraph/blob/main/Makefile.

The entire toolchain is FLOSS: Go (BSD-3-Clause), Node/npm (MIT), Make, Docker/BuildKit (Apache-2.0), Helm (Apache-2.0), and for the release path cosign, syft and Trivy (all Apache-2.0). Nothing proprietary is required to build, test or release. CGO_ENABLED=0 keeps the build free of a system C toolchain as well.

Two automated suites, both FLOSS: Go's standard testing package (BSD-3-Clause) for the backend, and Vitest (MIT) for the dashboard. How to run them is documented in CONTRIBUTING.md and wired into the Makefile (make test), and CI runs both on every push.

https://github.com/luiacuaniello/perspectivegraph/blob/main/CONTRIBUTING.md#dev-loop
https://github.com/luiacuaniello/perspectivegraph/blob/main/Makefile

go test ./... for the backend and npm test for the frontend — the standard invocation for each language, with no custom harness. make test runs the backend suite for convenience.

Statement coverage on the engine (internal/ and pkg/) is 81.1%, enforced by a CI gate that fails below 80% and uses cross-package attribution so a package tested through another still gets credit. 533 tests across 56 packages. Beyond unit tests: 11 Go fuzz targets against the ingest parsers, a deterministic hostile-input battery (11 collectors × 23 payloads) that runs on every build, -race across all packages, an integration suite against a real Apache AGE database, and a CloudGoat benchmark that measures the path-finding engine's precision and recall against declared ground truth.

Not covered: cmd/ sits at ~1% by design — it is process wiring, and the security-relevant parts of it (the production, auth and secret startup gates) are extracted into pure functions that are tested.

Every push and pull request runs build, go vet, tests, -race, staticcheck, gosec, govulncheck, the coverage gate, the frontend build/lint/test/audit, an Apache AGE integration job, container image scanning with Trivy, CodeQL, gitleaks and OpenSSF Scorecard. Fuzzing runs as its own workflow. Releases are automated end to end: release-please cuts the version, then binaries and multi-arch images are built, signed with cosign, and attested with an SBOM and SLSA provenance.

https://github.com/luiacuaniello/perspectivegraph/actions

CONTRIBUTING.md states it under "Conventions": "Tests (and a fuzz test for parsers) for new logic." The policy is enforced mechanically as well as socially — a coverage gate fails the build below 80% on internal/ and pkg/, so new logic without tests moves the number down and blocks the merge.

https://github.com/luiacuaniello/perspectivegraph/blob/main/CONTRIBUTING.md#conventions

Recent major changes each shipped with their tests, visible in the commit history. Examples: request correlation added internal/reqid with 8 tests including hostile-input cases; the file-based secret support added 8 tests plus 3 for the startup gate that refuses an unreadable secret; moving /metrics to its own listener added tests for both halves of the mux decision and for the configuration plumbing; the GraphQL cost guard added 6 tests, one of which reproduces a 1.2 KB document that previously took the guard over ten seconds to measure. The suite is 533 tests across 56 packages.

https://github.com/luiacuaniello/perspectivegraph/commits/main

The policy is in CONTRIBUTING.md, which is the instructions for change proposals, in the "Conventions" section alongside the exact CI commands to run locally before opening a pull request. The pull request template is in .github/PULL_REQUEST_TEMPLATE.md.

https://github.com/luiacuaniello/perspectivegraph/blob/main/CONTRIBUTING.md#conventions

Go: go vet on every build, plus staticcheck (which on introduction found real defects vet does not see), gosec for security patterns and govulncheck for vulnerable dependencies. Frontend: ESLint and the TypeScript compiler (tsc -b). All run in CI on every push and pull request.

https://github.com/luiacuaniello/perspectivegraph/blob/main/.github/workflows/ci.yml

Zero tolerance on both sides. Go is gated by vet, staticcheck and gosec; the frontend runs eslint . --max-warnings=0, so a warning fails the build exactly as an error does. Two suppressions exist, both scoped to the line or file where the decision was made and both carrying the reason inline: a rule false positive on factory-produced icon components, and a deliberate state reset inside a debounced effect whose cleared values are not in the effect's dependencies.

Maximally strict on both sides: no warning of any kind is tolerated in CI

The maintainer's professional field is cybersecurity software engineering, and the design record is public rather than asserted. The project's threat model enumerates trust boundaries and assets, then walks each surface with STRIDE, recording both the control and the residual risk — including cases where the residual is uncomfortable, such as an in-memory brute-force lockout that a restart clears.

The design applies least privilege (read-only cloud roles, viewer/admin RBAC, per-tenant isolation), fail-closed defaults (the binary refuses to start with SSO configured but issuer or audience missing, with credentials that parse to nothing, with an unreadable mounted secret, or with a declared production environment and an unreachable database), defence in depth (HMAC on ingest, rate limits with bounded state, query cost limits, a tamper-evident audit log, encryption at rest), and input validation at every trust boundary.

Common vulnerability classes are addressed explicitly, each with a countermeasure and a regression test:

Injection: parameterised queries; a hostile-input battery of 11 collectors × 23 payloads on every build; 11 fuzz targets on the parsers.
Broken authentication: constant-time token comparison; algorithm allowlist on JWT verification; mandatory issuer and audience, enforced by refusing to start — which closes the confused-deputy case where a token minted for another application sharing the same JWKS would otherwise be accepted.
Denial of service: body-size caps, per-IP rate limiting with a bounded client table, and GraphQL depth and cost budgets. A fragment-expansion bomb that stalled the guard for over ten seconds was found and fixed by memoisation; the reproduction is a permanent test.
Log injection: structured logging only, never message interpolation, verified empirically against a forged log line.
Prompt injection: environment-derived strings are bounded and neutralised before reaching the model, with the hostile inputs kept as a permanent test.
Supply chain: SHA-pinned Actions, digest-pinned base images, govulncheck, Trivy, CodeQL, gitleaks, cosign signatures, SBOM and SLSA provenance.

Only published, expert-reviewed primitives, all from the Go standard library: AES-GCM (NIST SP 800-38D), Ed25519 (RFC 8032), HMAC (RFC 2104), SHA-2 (FIPS 180-4), TLS 1.2/1.3 (RFC 5246 / RFC 8446), RSA-SSA with SHA-2 for JWT verification (RFC 7518), and PKCE S256 (RFC 7636). Nothing bespoke.

The project implements no cryptography. Every primitive is called from the Go standard library — crypto/aes, crypto/cipher, crypto/ed25519, crypto/hmac, crypto/sha256, crypto/rand, crypto/tls — and JWT verification uses the widely reviewed golang-jwt/jwt/v5, restricted to an explicit allowlist of signing methods so algorithm confusion is impossible. The one place the project writes protocol code by hand is the PKCE challenge, and that too calls crypto.subtle.digest("SHA-256") rather than implementing a hash.

All cryptography-dependent functionality runs on the Go standard library (BSD-3-Clause), golang-jwt/jwt/v5 (MIT), and the Web Crypto API in the browser. Verification tooling - cosign, syft, Trivy - is Apache-2.0. There is no proprietary or export-restricted component anywhere in the cryptographic path.

Defaults exceed the NIST minimums through 2030 and beyond: AES-256 for encryption at rest, Ed25519 (≈128-bit security) for signatures, SHA-256 for hashing and HMAC, TLS 1.2 as the floor with 1.3 preferred, and RSA JWT verification restricted to RS256/384/512.

Smaller keylengths cannot be selected at all: the algorithms and sizes are fixed in code with no configuration knob to weaken them, which satisfies the requirement more strongly than making the weakening merely disableable. The one length an operator supplies is the at-rest encryption key, which must be exactly 32 bytes or the process refuses to start.

No default security mechanism depends on a broken algorithm. No MD4, MD5, single DES, RC4 or Dual_EC_DRBG appears anywhere, and no CBC-mode construction is used - the at-rest cipher is AES-GCM, an AEAD. The only legacy primitive present is SHA-1, used solely for git-style content-addressed identifiers, never for authentication, integrity or confidentiality, and annotated inline where it appears. No interoperability constraint forces a weak algorithm on this project.

Defaults are modern: AES-256-GCM at rest, Ed25519 for export signatures, HMAC-SHA-256 for ingest authentication, SHA-256 for the audit hash chain, RS256/384/512 for JWT verification against the IdP's JWKS, PKCE with the S256 challenge method, and TLS with MinVersion: TLS 1.2. No MD5, DES, RC4 or CBC-mode construction anywhere.

One deliberate use of SHA-1 exists and is declared: pkg/ontology/event.go derives content-addressed node identifiers git-style. It is not a security primitive — the digest identifies a node, never authenticates or protects anything — and it is annotated inline (#nosec G505) so the intent is reviewable at the call site rather than hidden in a global exclude.

The project implements no key agreement of its own: all transport uses Go's standard crypto/tls with MinVersion: TLS 1.2, whose default cipher suite selection is ECDHE-based, and TLS 1.3 - negotiated whenever the peer supports it - provides forward secrecy unconditionally. The same applies to outbound connections (Postgres, NATS, IdP JWKS, LLM providers) and to TLS terminated at an ingress.

The software stores no user passwords. Authentication is either a bearer API token supplied by the operator, or OIDC, where the identity provider holds the credential and the project only verifies signed JWTs against its JWKS.

For completeness, since a reviewer will find it: a static API token may optionally be configured as sha256$<hex> so only its digest is stored. Plain SHA-256 is correct there and iterated hashing would not be: these are high-entropy random secrets, not user-chosen passwords, so there is no low-entropy guessing space for a work factor to defend. That is the same approach GitHub and Stripe take for API keys.

Every security-relevant value comes from crypto/rand: AES-GCM nonces (a fresh random nonce per seal), request identifiers, ticket and validation identifiers, and generated tokens.

math/rand/v2 appears only where determinism is the requirement and security is not involved: the Monte Carlo risk simulation and the uncertainty sampling, which are seeded deliberately so a before/after comparison reflects the change rather than sampling noise, plus the synthetic load and scenario generators used in testing. Those call sites carry an inline #nosec G404 stating exactly that.

Distribution channels use HTTPS exclusively. [osps_br_03_02]

Nothing is retrieved over http, and the hash is never trusted on its own. Releases publish SHA256SUMS together with SHA256SUMS.bundle, a cosign keyless signature over that file, so the documented verification order is signature first and checksum second — the README gives the exact command. Container images are signed with cosign and carry an SPDX SBOM and SLSA build provenance. Go dependencies are verified against go.sum and the public checksum database; GitHub Actions are pinned to commit SHAs; base images are pinned by digest; npm uses npm ci against a committed lockfile.

https://github.com/luiacuaniello/perspectivegraph#check-your-own-account-in-30-seconds

There are no unpatched vulnerabilities of any severity. No vulnerability has ever been publicly known against this project's own code, and dependencies are gated: govulncheck runs on every build against the Go vulnerability database, Trivy scans the release images, CodeQL performs taint analysis, and Dependabot opens update pull requests which are merged promptly. A finding in any of these fails CI, so an unpatched dependency cannot sit for 60 days — it blocks the next merge.

No critical vulnerability has been reported to date. The evidence that the project fixes security defects rapidly comes from its own auditing: a denial of service in the GraphQL cost guard (a 1.2 KB document that stalled the guard for over ten seconds), two unbounded maps reachable pre-authentication, and a production configuration that could start with authentication silently disabled were each found and fixed within the same working session, with regression tests that fail without the fix.

gitleaks scans the full history on every build and fails it on a finding; the last scan covered 116 commits with no leaks. .gitignore excludes .env, /secrets/, *.pem, *.key and *.crt. Credentials are never committed: the repository ships .env.example and .env.production.example with empty values, and the software additionally accepts every credential through a <KEY>_FILE path so it need not be written into a file at all.

https://github.com/luiacuaniello/perspectivegraph/blob/main/.github/workflows/ci.yml

Six static analysis tools run on every push and pull request, well beyond compiler warnings:

staticcheck, which on introduction found real defects that go vet does not see
gosec, security-focused SAST
CodeQL, semantic taint analysis
govulncheck, which reports reachable vulnerable code paths rather than merely vulnerable versions
gitleaks, secret scanning across the full history
ESLint and tsc for the dashboard
There is also a repository-specific gate: a test holds every configuration key the backend reads to all three deployment surfaces, so a key that is settable in one place and silently ignored in another fails the build.

https://github.com/luiacuaniello/perspectivegraph/blob/main/.github/workflows/ci.yml

Two of the tools are specifically vulnerability-oriented. gosec carries rules for the common Go classes: command and SQL injection, path traversal, weak cryptography, insecure randomness, unhandled errors. CodeQL performs dataflow taint tracking for the OWASP-style classes, following untrusted input to sensitive sinks across function boundaries. govulncheck goes further than a version comparison, reporting only vulnerabilities whose affected code the binary actually reaches.

Findings are fixed or justified inline, never suppressed globally. CONTRIBUTING.md forbids blanket excludes, so every suppression is a // #nosec Gxxx -- why it's safe comment at the call site where a reviewer will see it.

Two concrete cases. gosec raised G703 (path traversal via taint analysis) on the code that reads a mounted secret; it was reviewed, judged a false positive for that context (the path comes from an environment variable, and anyone who can set the process environment already owns it), and annotated with that reasoning rather than excluded. staticcheck raised ST1018 on a literal U+202E character in a test file, a Trojan Source pattern, which was replaced with an escape sequence.

All six tools currently report zero findings.

On every commit, not merely daily. staticcheck, gosec, govulncheck, go vet, gitleaks, ESLint and tsc run on every push and every pull request, and a finding fails the build. CodeQL runs on push and pull request and on a weekly schedule, so newly published query packs are applied to unchanged code. Extended fuzzing runs weekly on its own schedule.

https://github.com/luiacuaniello/perspectivegraph/actions

Three kinds of dynamic analysis run against the software as it executes.

Fuzzing: 14 Go fuzz targets against the ingest parsers, which are the boundary where attacker-influenceable bytes become graph structure. Their seed corpora execute on every go test, and a dedicated workflow runs extended campaigns weekly (Sunday, with a configurable duration on manual dispatch).

Race detection: go test -race across all 56 packages on every push. It instruments the running program to catch data races that no static tool sees.

A hostile-input battery: 11 collectors by 23 payloads (nesting bombs, invalid UTF-8, lone surrogates, 5 MB strings, path traversal, template injection, NUL bytes, bidirectional overrides), driven through the real parsers deterministically on every build. A 10-second per-payload timeout means a parser that can be stalled fails the test.

All of this runs before every release, since releases are cut from main only after CI is green.

https://github.com/luiacuaniello/perspectivegraph/blob/main/.github/workflows/fuzz.yml

The project produces no software in a memory-unsafe language. The backend is Go and the dashboard TypeScript, both memory-safe, and the backend is built with CGO_ENABLED=0 so no C is linked in. That also keeps the release binaries static and portable.

Fuzzing is nonetheless used extensively (14 targets), because in Go the classes it catches are panics, unbounded allocation and non-termination rather than buffer overwrites.

The race detector is the Go analogue of an assertion-heavy build, and it is enabled exactly where the criterion suggests: -race runs across all packages in CI, and is not enabled in production builds, which are CGO_ENABLED=0 static binaries.

Tests additionally assert invariants that production code does not re-check. Two examples: the hand-rolled priority queue must agree with container/heap element by element on randomised input full of ties, and scoring output must stay byte-identical across an optimisation.

No unfixed finding exists. The clearest example of the process working came from dynamic analysis of the GraphQL cost guard. A purpose-built probe timed the guard against a 1.2 KB document of non-cyclic fragments and showed it running for over ten seconds before a single field resolved, which is a denial of service in the very guard meant to prevent one. It was fixed in the same session by memoising fragment costs (49 µs for the same input), and the reproduction is now a permanent test that fails if the expansion stops being linear.

Race-detector and fuzzing runs are currently clean.