spector

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

The project explicitly identifies small, accessible tasks for new and casual contributors in CONTRIBUTING.md under Good First Areas (https://github.com/spectrayan/spector/blob/main/CONTRIBUTING.md#good-first-areas) and in the GitHub issue tracker via the standard good first issue label (https://github.com/spectrayan/spector/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). Documented beginner-friendly tasks include documentation and tutorial improvements, edge-case test coverage in spector-core, implementing isolated EmbeddingProvider SPI templates, CLI output ergonomics in spector-cli, and building UI widgets for spector-cortex, backed by first-time onboarding guidance in the 4-tier Contributor Ladder (https://github.com/spectrayan/spector/blob/main/GOVERNANCE.md#3-the-4-tier-contributor-ladder).

GitHub requires 2FA as of March 2023. [osps_ac_01_01]

The project enforces cryptographically secure two-factor authentication (2FA) across its code repository, package registries, and administrative accounts, documented in GOVERNANCE.md under Project Continuity & Redundancy (https://github.com/spectrayan/spector/blob/main/GOVERNANCE.md#32-project-continuity--redundancy) and SECURITY.md (https://github.com/spectrayan/spector/blob/main/SECURITY.md). Maintainers and repository administrators authenticate using FIDO2/WebAuthn cryptographic hardware security keys and TOTP authenticator applications (RFC 6238), with SMS-based 2FA prohibited. Automated distribution pipelines (GHCR, PyPI, and npm) utilize cryptographic OpenID Connect (OIDC) token exchanges and scoped publisher tokens to eliminate static credentials and prevent impersonation attacks.

The project formally documents its code review requirements in CONTRIBUTING.md under Code Review Requirements (https://github.com/spectrayan/spector/blob/main/CONTRIBUTING.md#code-review-requirements) and GOVERNANCE.md (https://github.com/spectrayan/spector/blob/main/GOVERNANCE.md#2-governance-structure--roles). Code review is conducted publicly on GitHub Pull Requests by authorized Committers and Maintainers designated in .github/CODEOWNERS (https://github.com/spectrayan/spector/blob/main/.github/CODEOWNERS). Reviewers must verify: (1) automated test coverage and regression tests; (2) security and memory safety (no hardcoded secrets, input allowlisting, Panama FFM bounded arena safety); (3) architectural invariants (zero-dependency rule in engine core); (4) performance criteria (zero allocations on SIMD hot paths, JMH benchmarks); and (5) licensing compliance (DCO 1.1 sign-off, Apache 2.0 headers). Acceptance requires passing all automated CI matrix and CodeQL checks, resolving all reviewer threads, and receiving formal approval from the assigned CODEOWNER.

The project enforces mandatory independent peer review on all proposed modifications prior to release, exceeding the 50% requirement. Documented in CONTRIBUTING.md under Code Review Requirements (https://github.com/spectrayan/spector/blob/main/CONTRIBUTING.md#code-review-requirements) and GOVERNANCE.md (https://github.com/spectrayan/spector/blob/main/GOVERNANCE.md#4-decision-making--voting-mechanics), every pull request targeting main must be evaluated and approved by an independent committer or maintainer other than the author (governed by .github/CODEOWNERS: https://github.com/spectrayan/spector/blob/main/.github/CODEOWNERS). The full history of peer reviews, approvals, and maintainer feedback is publicly verifiable across merged pull requests in the repository (https://github.com/spectrayan/spector/pulls?q=is%3Apr+is%3Amerged).

The project implements reproducible builds in accordance with reproducible-builds.org specifications via Apache Maven's build configuration in pom.xml (https://github.com/spectrayan/spector/blob/main/pom.xml#L189-L191). By declaring a fixed timestamp (<project.build.outputTimestamp>2024-01-01T00:00:00Z</project.build.outputTimestamp>), the build system normalizes file ordering, permissions, and archive entry timestamps across all generated JAR and ZIP artifacts (via maven-jar-plugin, maven-shade-plugin, and flatten-maven-plugin). Repeated compilation of the source tree in the same OpenJDK 25 environment yields bit-for-bit identical binary distributions without non-deterministic drift.

The test suite is invoked using standard language conventions: mvn test for the Java Maven reactor, npm test for TypeScript modules, and pytest for the Python SDK. https://github.com/spectrayan/spector/blob/main/CONTRIBUTING.md#running-the-test-suites

Continuous integration is implemented using GitHub Actions (.github/workflows/ci.yml). Automated builds, multi-architecture matrix tests (x86_64 and aarch64), license checks, and property tests run on every pull request and commit to main. https://github.com/spectrayan/spector/actions

The project uses the open-source JaCoCo tool (jacoco-maven-plugin: https://github.com/spectrayan/spector/blob/main/pom.xml#L1046-L1048) in its automated CI pipeline in .github/workflows/ci.yml (https://github.com/spectrayan/spector/blob/main/.github/workflows/ci.yml#L134-L142) to measure statement and branch coverage. Automated test suites—comprising JUnit 5 unit tests, jqwik property-based generative invariant tests, and integration pathways—exercise the codebase on every check-in, achieving and maintaining over 90% statement coverage across core memory layout, decay math, SIMD vector scoring, and kernel persistence modules.

The project measures and validates branch coverage using the open-source JaCoCo framework (jacoco-maven-plugin: https://github.com/spectrayan/spector/blob/main/pom.xml#L1046-L1048), executed automatically in CI via .github/workflows/ci.yml (https://github.com/spectrayan/spector/blob/main/.github/workflows/ci.yml#L134-L142). The automated test suite combines traditional unit tests with comprehensive jqwik property-based generative testing hat systematically explores boundary inputs, bit-flip conditions, and error-handling paths, maintaining at least 80% branch coverage across the core engine and indexing modules.

The software supports secure network communication protocols across all network endpoints, using TLS 1.2 and TLS 1.3 for HTTPS REST APIs, gRPC services, and inter-node cluster replication, documented in docs/architecture/encryption-at-rest.md (https://github.com/spectrayan/spector/blob/main/docs/architecture/encryption-at-rest.md) and synapse/spector-synapse/src/main/java/com/spectrayan/spector/synapse/replication/ReplicationTlsFactory.java (https://github.com/spectrayan/spector/blob/main/synapse/spector-synapse/src/main/java/com/spectrayan/spector/synapse/replication/ReplicationTlsFactory.java). Insecure and legacy protocols (such as FTP, Telnet, SSLv2, SSLv3, and TLS 1.0/1.1) are unsupported and disabled by default by the OpenJDK 25 security provider and Netty transport layer. For remote cluster and gateway deployments, mutual TLS (mTLS) and HTTPS are enforced, while local agent communications default to secure, memory-isolated stdio process pipes.

The software natively supports TLS 1.2 and modern TLS 1.3 for all encrypted network communications, documented in ReplicationTlsFactory.java (https://github.com/spectrayan/spector/blob/main/synapse/spector-synapse/src/main/java/com/spectrayan/spector/synapse/replication/ReplicationTlsFactory.java#L46-L50) and docs/architecture/encryption-at-rest.md (https://github.com/spectrayan/spector/blob/main/docs/architecture/encryption-at-rest.md). Cluster node replication explicitly enforces TLS 1.3 contexts (public static final String TLS_V1_3 = "TLSv1.3"), and gateway REST/gRPC endpoints support both TLS 1.2 and TLS 1.3 through the OpenJDK 25 and Netty SSL engines. All legacy protocols prior to TLS 1.2 (SSLv2, SSLv3, TLS 1.0, TLS 1.1) are permanently disabled at the runtime platform level.

The project repository, documentation website, and release distribution sites enforce key hardening headers with nonpermissive values. The primary code repository and release download endpoints hosted on GitHub (https://github.com/spectrayan/spector) enforce strict HTTP headers including Strict-Transport-Security: max-age=31536000; includeSubdomains; preload, X-Frame-Options: deny, X-Content-Type-Options: nosniff, and a restrictive Content-Security-Policy with frame-ancestors 'none'. The documentation website hosted on GitHub Pages (https://spectrayan.github.io/spector/) strictly enforces HTTP Strict Transport Security (Strict-Transport-Security: max-age=31556952), and the Synapse server gateway in SecurityConfig.java (https://github.com/spectrayan/spector/blob/main/synapse/spector-synapse/src/main/java/com/spectrayan/spector/synapse/config/SecurityConfig.java) activates Spring Security's default nonpermissive header suite (nosniff, frame denial, and HSTS).

The project completed a comprehensive architectural and code security review in September 2026, documented in the formal Security Assurance Case & Threat Model (https://github.com/spectrayan/spector/blob/main/docs/architecture/security-assurance.md) and linked in SECURITY.md (https://github.com/spectrayan/spector/blob/main/SECURITY.md). The review explicitly evaluated the system's security requirements and mapped its five core security trust boundaries (network-to-gateway, agent-to-MCP, tenant-to-tenant, JVM-to-native off-heap, and host storage), verifying mitigations against memory corruption, path traversal, untrusted input injection, and timing attacks. This is augmented by automated continuous security reviews in CI via GitHub CodeQL (https://github.com/spectrayan/spector/blob/main/.github/workflows/codeql.yml) and Aqua Trivy container scanning.

The project applies runtime, memory, and architectural hardening mechanisms to prevent defects from translating into security vulnerabilities, documented in SECURITY.md under Security Guarantees & Non-Guarantees (https://github.com/spectrayan/spector/blob/main/SECURITY.md#security-guarantees--non-guarantees-security-requirements) and docs/architecture/overview.md (https://github.com/spectrayan/spector/blob/main/docs/architecture/overview.md). Off-heap native memory accesses are hardened using OpenJDK 25 Project Panama bounded Arena lifecycles that enforce spatial and temporal boundary checks at the JVM level, preventing memory corruption, use-after-free, and buffer overflows. Authentication endpoints enforce constant-time string comparisons to eliminate timing side-channels, binary headers enforce hardware CRC32C integrity checksums and strict format-version gates, and container images run under restricted non-root users with pinned base image digests.

The project applies dynamic analysis prior to release using multiple FLOSS tools: jqwik for dynamic randomized property-based testing and fuzzing of algorithmic invariants, PanamaMemoryDetector for dynamic off-heap memory leak tracking, JaCoCo for runtime bytecode coverage analysis, and automated live container smoke testing prior to release publication.