mirror of
https://github.com/ruvnet/RuVector.git
synced 2026-08-26 09:02:48 +00:00
4c6da3b30d
Four rounds of security review kept finding the same shape: a sensitive thing placed under a NAME in the attacker-writable root, defended by a check on that name, and the next round swapped the next name. The scratch name moved inside a private staging directory -- and then the staging directory was itself a name in the root, so it was swappable too. The review demonstrated 274 victim rows readable outside the root after erase_scope reported success. There is no fixed point on that path, because every component under the root is re-resolved on every syscall and this crate holds none of them by descriptor. Two things terminate it: descriptor-anchored I/O, which needs an fd- or directory-relative open in the vector engine and is therefore an engine-level change, or removing the hostile directory from the threat model. This takes the second. It also settles a finding that made the rest academic: under a normal umask shards were published 0644 inside a 0755 root, so a different-uid attacker could read every tenant's vectors with no exploit at all. The staging directory was protecting a shard for the milliseconds it was being built and then publishing it world-readable. The root is now created 0700 by mkdir itself, shards and the lock are created 0600, and open refuses a root that is group- or other-accessible, reporting the offending mode without the path. An existing root is inspected and never modified, so an operator's deliberate permissions are reported rather than silently widened or narrowed. Observed on disk under both umask 022 and umask 000: root 0700, lock 0600, shard 0600, staging 0700. The staging directory, the inode identity check, the lone-regular-file requirement and the reserved-name sweep are all kept, but they are now defence in depth against operator error rather than the boundary itself, and their docs say so. The nlink documentation is corrected in particular: a link count of one means only that no second name existed at the instant of the lstat, not that the file is this index's, and the private root rather than that check is what prevents a second name. An attacker running as the same uid remains conceded, and content forgery remains out of scope for want of a MAC over stored vectors. Both are stated in the crate docs, the tests, and ADR-334. Note for reviewers: tempfile::tempdir() creates 0755, so the new check refused every existing test root and the suite now builds its roots at 0700 explicitly. That default is exactly the class of mistake that produced the world-readable shards. Co-Authored-By: claude-flow <ruv@ruv.net> Claude-Session: https://claude.ai/code/session_016QSCkKnxDjqU49NVVpWMK5 |
||
|---|---|---|
| .. | ||
| adr | ||
| analysis | ||
| api | ||
| architecture | ||
| benchmarks | ||
| cloud-architecture | ||
| cnn | ||
| code-reviews | ||
| dag | ||
| decisions | ||
| development | ||
| evidence | ||
| examples | ||
| gnn | ||
| guides | ||
| hailo | ||
| hnsw | ||
| hooks | ||
| implementation | ||
| integration | ||
| nervous-system | ||
| optimization | ||
| plans | ||
| postgres | ||
| project-phases | ||
| publishing | ||
| releases | ||
| research | ||
| reviews | ||
| ruvllm | ||
| rvagent | ||
| rvforge | ||
| sdk | ||
| security | ||
| sonic-ct | ||
| sparse-inference | ||
| sql | ||
| testing | ||
| training | ||
| .gitkeep | ||
| .nojekyll | ||
| agi-container.md | ||
| C2-shell-execution-hardening.md | ||
| C8_RESULT_VALIDATION_IMPLEMENTATION.md | ||
| consciousness-api.md | ||
| IMPLEMENTATION-C5.md | ||
| index.html | ||
| INDEX.md | ||
| METAHARNESS-ARCHITECTURE-SUMMARY.md | ||
| metaharness-implementation-plan.md | ||
| moe-routing-optimization-analysis.md | ||
| README.md | ||
| REPO_STRUCTURE.md | ||
| research-openfang.md | ||
RuVector Documentation
Complete documentation for RuVector, the high-performance Rust vector database with global scale capabilities.
📚 Documentation Structure
docs/
├── adr/ # Architecture Decision Records
├── analysis/ # Research & analysis docs
├── api/ # API references (Rust, Node.js, Cypher)
├── architecture/ # System design docs
├── benchmarks/ # Performance benchmarks & results
├── cloud-architecture/ # Cloud deployment guides
├── code-reviews/ # Code review documentation
├── dag/ # DAG implementation
├── development/ # Developer guides
├── examples/ # SQL examples
├── gnn/ # GNN/Graph implementation
├── guides/ # User guides & tutorials
├── hnsw/ # HNSW index documentation
├── hooks/ # Hooks system documentation
├── implementation/ # Implementation details & summaries
├── integration/ # Integration guides
├── nervous-system/ # Nervous system architecture
├── optimization/ # Performance optimization guides
├── plans/ # Implementation plans
├── postgres/ # PostgreSQL extension docs
├── project-phases/ # Development phases
├── publishing/ # NPM publishing guides
├── research/ # Research documentation
├── ruvllm/ # RuVLLM documentation
├── security/ # Security audits & reports
├── sparse-inference/ # Sparse inference docs
├── sql/ # SQL examples
├── testing/ # Testing documentation
└── training/ # Training & LoRA docs
Getting Started
- guides/GETTING_STARTED.md - Getting started guide
- guides/BASIC_TUTORIAL.md - Basic tutorial
- guides/INSTALLATION.md - Installation instructions
- guides/AGENTICDB_QUICKSTART.md - AgenticDB quick start
- guides/wasm-api.md - WebAssembly API documentation
Architecture & Design
- architecture/ - System architecture details
- cloud-architecture/ - Global cloud deployment
- adr/ - Architecture Decision Records
- nervous-system/ - Nervous system architecture
API Reference
- api/RUST_API.md - Rust API reference
- api/NODEJS_API.md - Node.js API reference
- api/CYPHER_REFERENCE.md - Cypher query reference
Performance & Benchmarks
- benchmarks/ - Performance benchmarks & results
- optimization/ - Performance optimization guides
- analysis/ - Research & analysis docs
Security
- security/ - Security audits & reports
Implementation
- implementation/ - Implementation details & summaries
- integration/ - Integration guides
- code-reviews/ - Code review documentation
Specialized Topics
- gnn/ - GNN/Graph implementation
- hnsw/ - HNSW index documentation
- postgres/ - PostgreSQL extension docs
- ruvllm/ - RuVLLM documentation
- training/ - Training & LoRA docs
Development
- development/CONTRIBUTING.md - Contribution guidelines
- development/MIGRATION.md - Migration guide
- testing/ - Testing documentation
- publishing/ - NPM publishing guides
Research
- research/ - Research documentation
- cognitive-frontier/ - Cognitive frontier research
- gnn-v2/ - GNN v2 research
- latent-space/ - HNSW & attention research
- mincut/ - MinCut algorithm research
🚀 Quick Links
For New Users
- Start with Getting Started Guide
- Try the Basic Tutorial
- Review API Documentation
For Cloud Deployment
- Read Architecture Overview
- Follow Deployment Guide
- Apply Performance Optimizations
For Contributors
- Read Contributing Guidelines
- Review Architecture Decisions
- Check Migration Guide
For Performance Tuning
- Review Optimization Guide
- Run Benchmarks
- Check Analysis
📊 Documentation Status
| Category | Directory | Status |
|---|---|---|
| Getting Started | guides/ | ✅ Complete |
| Architecture | architecture/, adr/ | ✅ Complete |
| API Reference | api/ | ✅ Complete |
| Performance | benchmarks/, optimization/, analysis/ | ✅ Complete |
| Security | security/ | ✅ Complete |
| Implementation | implementation/, integration/ | ✅ Complete |
| Development | development/, testing/ | ✅ Complete |
| Research | research/ | 📚 Ongoing |
Total Documentation: 460+ documents across 60+ directories
🔗 External Resources
- GitHub Repository: https://github.com/ruvnet/ruvector
- Main README: ../README.md
- Changelog: ../CHANGELOG.md
- License: ../LICENSE
Last Updated: 2026-02-26 | Version: 2.0.4 (core) / 0.1.100 (npm) | Status: Production Ready