Skip to main content

Privacy & Security

Constellation CLI is built from the ground up with a privacy-first architecture that ensures your proprietary code never leaves your environment. Every design decision prioritizes the security and confidentiality of your intellectual property while delivering powerful code intelligence capabilities.

Core Privacy Principles​

Your Code Never Leaves Your Machine​

Constellation operates on a fundamental principle: your source code is your most valuable asset. Unlike traditional code analysis tools that upload entire codebases to cloud servers, Constellation performs all code parsing and initial processing locally on your system.

How it works:

  1. All source code parsing happens directly on your local system using high-performance parsers
  2. Source code metadata is generated locally with source text removed
  3. Only the serialized metadata is compressed and transmitted
  4. The Constellation service receives only structural metadata, never source code
  5. Intelligence extraction happens server-side using only the metadata
  6. Extracted intelligence is indexed into your team's knowledge graph

Why this matters:

  • Your proprietary algorithms, business logic, and trade secrets remain private.
  • No risk of source code exposure.
  • Compliance with strict corporate security policies and regulatory requirements.
  • Peace of mind when working with sensitive or classified codebases.

Advanced Security Features​

Source Code Metadata Only Transmission​

Constellation employs a sophisticated metadata-only approach that completely eliminates the risk of source code exposure while maintaining full analytical capabilities.

Technical Implementation:

  1. Local Metadata Generation: Local parsers extract only the structural representation of your code
  2. Source Text Removal: Source code text is stripped from metadata before serialization
  3. Metadata Only: Only metadata about code structure, symbols, and relationships is transmitted
  4. Irreversible Process: The original source code cannot be reconstructed from the metadata

Security Benefits:

  • Zero source code exposure: If transmitted data were intercepted, it contains no actual code.
  • Intellectual property protection: Your unique implementations and algorithms remain confidential.
  • Reduced attack surface: Metadata is meaningless without context, providing no value to attackers.

Intelligent Compression & Minimal Data Transfer​

Every byte of data transmitted is optimized for both security and efficiency.

Compression Architecture:

  • Metadata is compressed using industry-standard gzip compression
  • Reduces data size by up to 90%
  • NDJSON streaming protocol enables efficient processing of large codebases
  • Smaller payloads mean faster transmission
  • Compression adds an additional layer of obfuscation

Network Security:

  • All transmissions use TLS 1.3+ encryption
  • NDJSON streaming for efficient, memory-conscious data transfer
  • Automatic retry with exponential backoff for network resilience

Scalability Without Compromise​

No Artificial Limits on Codebase Size​

Unlike many analysis tools that impose arbitrary limits, Constellation is engineered to handle codebases of any size without compromising privacy or performance.

Scalable Design:

  • NDJSON streaming architecture handles files of any size
  • Stream processing ensures constant memory usage
  • Incremental indexing processes only changed files
  • Full indexing available when needed for complete updates

Performance at Scale:

  • Processes multi-million line codebases efficiently
  • Handles large files without memory constraints
  • Continues processing even if individual files fail

Memory-Efficient Streaming Architecture​

Constellation's streaming architecture ensures that even the largest files are processed without memory constraints or security risks.

Stream Processing Benefits:

  • NDJSON streaming processes metadata in batches
  • Constant memory usage regardless of file sizes
  • No temporary files that could expose sensitive data
  • Efficient transmission minimizes network overhead

Respecting Your Development Environment​

Git-Aware Security​

Constellation intelligently integrates with your existing Git configuration to respect your security boundaries.

Git Integration Features:

  • Automatic .gitignore adherence: Files you've marked to be ignored by git will never be processed
  • Branch validation: Ensures indexing happens on the correct branch to prevent index pollution
  • Working tree validation: Prevents indexing uncommitted changes (unless explicitly bypassed for testing)
  • Repository boundary awareness: Avoids accidentally processing files outside your project

Project Boundary Protection​

Constellation maintains strict boundaries to ensure only intended code is analyzed.

Boundary Enforcement:

  • Explicit project root detection prevents accidental scanning.
  • Symlink resolution respects security boundaries.
  • Hidden file handling follows Unix conventions.
  • Clear user confirmation for any cross-boundary operations.

Data Handling & Retention​

Zero-Knowledge Architecture​

Constellation's servers operate on a zero-knowledge principle, they never see or store your actual source code.

Server-Side Processing:

  • Servers receive only source code metadata, never source code
  • Intelligence extraction works entirely with structural data from metadata
  • Symbols, relationships, and patterns are extracted and indexed into knowledge graphs
  • No reconstruction of original code is possible or attempted
  • Analysis results reference structural information, not source content

Data Lifecycle:

  1. CLI transmits compressed source code metadata via NDJSON streaming
  2. Service receives and processes metadata to extract code intelligence
  3. Extracted intelligence (symbols, relationships, metadata) is indexed into knowledge graphs
  4. Knowledge graphs power code intelligence tools for your team
  5. Original metadata is not persistently stored - only extracted intelligence is retained

Transparent Data Flow​

Understanding exactly what data flows through the system builds trust and ensures compliance.

Data Flow Transparency:

What Gets Transmitted:

  • Symbol names and types (functions, classes, variables, etc.)
  • Code structure and nesting relationships
  • Import and export statements
  • Function signatures and type information
  • Relationships between symbols (calls, inheritance, etc.)

What NEVER Gets Transmitted:

  • Source code text or implementation details
  • Comments or documentation strings
  • Variable values or literals
  • Proprietary algorithms or business logic

Architectural Security Decisions​

Intelligence Extraction Architecture​

The decision to perform intelligence extraction server-side is a carefully considered architectural choice that enhances both security and consistency.

Why Server-Side Intelligence:

  • Consistency: Uniform analysis across all clients ensures reliable, deterministic results
  • Team Collaboration: Centralized knowledge graphs enable team-wide code intelligence
  • Updates: Improvements and enhancements are instantly available to all users
  • Efficiency: Powerful graph-based analysis without local processing overhead
  • Privacy: Only source code metadata needed for extraction, source code never required

Client-Server Separation:

  • Client: Parsing, metadata generation (with source removal), compression, streaming transmission
  • Server: Intelligence extraction from metadata, knowledge graph indexing, query processing
  • Result: Maximum privacy with powerful team-wide analytical capabilities

Security Checklist​

✅ Before using Constellation:

  • Ensure .gitignore includes all sensitive files
  • Review project boundaries and included paths in constellation.json
  • Configure exclude patterns for any additional paths to skip
  • Verify network security (firewall rules, VPN if required)
  • Ensure you're on the correct git branch before indexing

✅ During operation:

  • Monitor the CLI output for processing progress
  • Verify only intended files are being processed
  • Use incremental indexing for routine updates
  • Use full indexing only when needed (major refactors, branch changes)
  • Avoid using --dirty flag in production (testing only)

Frequently Asked Questions​

Can my source code be reconstructed from the metadata?​

No. Source code metadata is a structural representation that captures relationships and patterns but not the actual implementation. It's like having a blueprint that shows room layouts but not the furniture inside them. The original code, including your proprietary algorithms and business logic, cannot be reconstructed.

What about dependencies and third-party libraries?​

Constellation intelligently handles dependencies:

  • Respects node_modules, vendor, and similar directories.
  • Analyzes only your code by default, not third-party libraries.
  • Clear boundaries between your code and external dependencies.

Trust Through Transparency​

We believe that security through obscurity is not security at all. That's why we're completely transparent about how Constellation protects your code:

  • Open architecture documentation: Understand exactly how the system works.
  • Public security audits: Third-party validation of our security claims.
  • Regular security updates: Proactive patching and enhancement.