Fimeg/RedFlag
Watch
1
0
Fork
You've already forked RedFlag
 0
Code Releases 1 Activity
RedFlag/RAF/reference/01-file-mappings.md
Fimeg 67e26be2d9 projection: begin the exact-path public epoch 
The public tree and its history contain only the listed paths. Earlier projection history remains preserved internally.

Source-Sha: 913fde029b935671833254797f0f20f1eb9fabba

Policy-Sha: 913fde029b935671833254797f0f20f1eb9fabba

Tree-Digest: 180ae530c1058a2a5c89837bdce2d323ae83e669e38590ca72e75b8d92b7262f
2026-09-08 21:59:33 -04:00

141 lines
7 KiB
Markdown
Raw Blame History

# File Mappings
**Complete mapping of architectural concepts to source files.**
---
## Core Files
| Concept | File | Purpose |
|---------|------|---------|
| ETHOS principles | `RAF/core/01-ethos.md` | Core identity and principles |
| Architecture decisions | `RAF/core/02-architecture-decisions.md` | Key architectural choices |
| Server component | `RAF/components/01-server.md` | Server breakdown |
| Trust boundaries | `RAF/security/01-trust-boundaries.md` | Trust boundary matrix |
| Auth stack | `RAF/security/02-authentication-stack.md` | Four-layer auth |
| Machine binding | `RAF/security/04-machine-binding.md` | Hardware verification |
| Signing pipeline | `RAF/verification/01-signing-pipeline.md` | Ed25519 signing |
| Agent verification | `RAF/verification/02-agent-verification.md` | TOFU key caching |
| Key rotation | `RAF/verification/03-key-rotation.md` | Key rotation support |
| Replay protection | `RAF/verification/04-replay-protection.md` | Multi-layer defense |
| Registration flow | `RAF/flows/01-registration.md` | TOFU registration |
| Command execution | `RAF/flows/02-command-execution.md` | Polling and dispatch |
| Heartbeat | `RAF/flows/04-heartbeat.md` | Health monitoring |
| Capability advertisement | `RAF/flows/05-capability-advertisement.md` | Dynamic scanner reporting |
| Windows Updates | `RAF/scanners/01-windows-updates.md` | WUA integration |
| Docker Scanner | `RAF/scanners/02-docker-scanner.md` | Docker image scanning |
| APT Scanner | `RAF/scanners/03-apt-scanner.md` | APT package manager |
| DNF Scanner | `RAF/scanners/04-dnf-scanner.md` | DNF package manager |
| Process Scanner | `RAF/scanners/05-process-scanner.md` | On-demand /proc scanning |
| Process Scan Flow | `RAF/flows/07-process-scan.md` | Process inventory and drill-down |
---
## Source Files
### Server
| File | Purpose |
|------|---------|
| `server/cmd/server/main.go` | Entry point, route registration |
| `server/internal/api/handlers/agents.go` | Agent CRUD, registration, rebind |
| `server/internal/api/handlers/subsystems.go` | Subsystem CRUD, enable/disable with scheduler eviction |
| `server/internal/api/handlers/agent_updates.go` | Update approval, trigger |
| `server/internal/api/handlers/downloads.go` | Binary distribution |
| `server/internal/api/handlers/setup.go` | Setup wizard, key generation |
| `server/internal/api/middleware/auth.go` | JWT validation |
| `server/internal/api/middleware/machine_binding.go` | Hardware verification |
| `server/internal/database/db.go` | DB connection, migrations |
| `server/internal/database/queries/subsystems.go` | Scanner sync queries |
| `server/internal/database/queries/docker.go` | Docker image queries |
| `server/internal/services/signing.go` | Ed25519 signing |
| `server/internal/services/build_orchestrator.go` | Binary signing |
| `server/internal/services/update_nonce.go` | Replay protection (update nonces) |
| `server/internal/services/timeout.go` | Timeout configuration |
| `server/internal/api/handlers/processes.go` | Process scan endpoints (report, list, detail, trigger) |
| `server/internal/database/queries/processes.go` | Process snapshot queries |
| `server/internal/models/process.go` | Process data models |
| `server/internal/database/migrations/055_create_process_tables.up.sql` | Process tables schema |
| `server/internal/scheduler/scheduler.go` | Subsystem job scheduling, priority queue |
| `server/internal/scheduler/queue.go` | Priority queue (heap) for scheduled jobs |
### Agent
| File | Purpose |
|------|---------|
| `agent/internal/agent/loop.go` | Polling loop implementation |
| `agent/internal/system/machine_id.go` | Machine ID generation |
| `agent/internal/registration/service.go` | Agent registration |
| `agent/internal/config/config.go` | Config management |
| `agent/internal/client/client.go` | API client with retry |
| `agent/internal/orchestrator/docker_scanner.go` | Docker scanner + registry client |
| `agent/internal/orchestrator/storage_scanner.go` | Storage/disk scanner |
| `agent/internal/orchestrator/system_scanner.go` | System metrics scanner |
| `agent/internal/orchestrator/orchestrator.go` | Scanner orchestration, circuit breaker integration |
| `agent/internal/orchestrator/command_handler.go` | Receipt/ack tracking |
| `agent/internal/orchestrator/update_handler.go` | Update handler |
| `agent/internal/circuitbreaker/circuitbreaker.go` | Circuit breaker |
| `agent/internal/retry/retry.go` | Exponential backoff |
| `agent/internal/crypto/pubkey.go` | Public key caching (TOFU) |
| `agent/internal/crypto/verification.go` | Signature verification |
| `agent/internal/scanner/apt.go` | APT scanner |
| `agent/internal/scanner/dnf.go` | DNF scanner |
| `agent/pkg/windowsupdate/client.go` | Windows Update client |
| `agent/internal/system/machine_id.go` | Machine ID generation (Linux) |
### Web
| File | Purpose |
|------|---------|
| `web/src/App.tsx` | Main app + routing |
| `web/src/pages/Agents.tsx` | Agent management |
| `web/src/pages/Updates.tsx` | Update management |
| `web/src/pages/Settings.tsx` | Settings pages |
| `web/src/pages/Dashboard.tsx` | Dashboard |
| `web/src/components/AgentHealth.tsx` | Health monitoring |
| `web/src/components/primitives/` | UI primitive library — FilterBar, SearchInput, FilterDropdown, FilterPill, FilterCountButton, SortableTable, StateBadge, CommandCard, CommandStatusBadge, Modal, PageState, Pagination, StatCard, ScreenshotCard, MetricItem, ProcessTable |
| `web/src/hooks/useFilterUrl.ts` | URL-synced filter state |
| `web/src/hooks/useQueryParser.ts` | key:value query string parser |
| `web/src/hooks/useMultimodalFilter.ts` | Composed multimodal filter |
| `web/src/hooks/useDebounce.ts` | Generic debounce |
| `web/src/hooks/useColumnSort.tsx` | Reusable column sort |
| `web/src/hooks/useCommands.ts` | TanStack Query hook |
| `web/src/hooks/useAgents.ts` | Agent data hook |
---
## Database Tables
| Table | Purpose |
|-------|---------|
| `agents` | Agent records |
| `agents_metadata` | Metadata (available_scanners, heartbeat_source, last_heartbeat) |
| `agent_subsystems` | Enabled scanners (idempotent sync) |
| `agent_commands` | Pending commands |
| `update_logs` | Update execution history |
| `system_events` | Operational events (scans, heartbeats) |
| `refresh_tokens` | Refresh token lifecycle |
| `registration_tokens` | One-time registration tokens |
| `server_public_keys` | Ed25519 keys (rotation support) |
| `security_settings` | Policy configuration |
| `tracked_software` | Agent ↔ tracked_software bindings |
---
## Footer: Assumptions & Connections
**Assumption:** File mappings are living documents — update when code changes.
**Connection:** Core files (`RAF/core/`) provide the foundational principles for all other sections.
**Connection:** Security files (`RAF/security/`) define trust boundaries that all flows must respect.
**Connection:** Verification files (`RAF/verification/`) implement the cryptographic guarantees.
**Connection:** Flow files (`RAF/flows/`) show how components interact end-to-end.
**Connection:** Scanner files (`RAF/scanners/`) document platform-specific integrations.
---
*Last reviewed: 2026-05-26*
View git blame Copy permalink