Source preview guide · 0.1.0
How CodeSecurity fits together
Follow source authority, durable jobs and scanner evidence through the local workbench.
CodeSecurity is a local security workbench with two clients: the browser dashboard and the VS Code extension. FastAPI serves the compiled React application and the control API. PostgreSQL retains application state. A separate worker executes durable commands against the scanner, scanner-data updater and optional Advisor connector.
Follow one scan from saved source to retained evidence. Each service has a narrow role and its own authority boundary.
Follow one scan through the system
Operator clients
- Browser
Paired operator session and Web workbench.
- VS Code
One approved editor profile with scoped capabilities.
Local entry and durable state
- Loopback relay
Publishes the local TCP endpoint without runtime secrets or persistent mounts.
- FastAPI + React
Serves the workbench and checks control requests. It has no Docker socket.
- PostgreSQL
Retains installation state, commands, jobs, findings and policy.
- Job worker
Claims durable work and coordinates its result.
Bounded execution services
- Scanner
Reads authorized source and validated data on an internal network.
- Updater
Fetches reviewed scanner data without a project-source mount.
- Advisor connector
Executes optional provider requests under exact grants.
Data and optional provider
- Validated scanner cache
Runtime readers see a selected read-only generation.
- Authorized Ollama provider
Local or explicitly authorized remote destination.
Connections
Browser to Loopback relay
Browser requests enter through the loopback endpoint.
VS Code to Loopback relay
Editor requests use the same endpoint with their own authority.
Loopback relay to FastAPI + React
The relay forwards TCP traffic to the control service.
FastAPI + React to PostgreSQL
Control state is read and changed through admitted operations.
Job worker to PostgreSQL
Job leases and outcomes are persisted independently of the client page.
Job worker to Scanner
The worker submits bounded scan work and collects results.
Job worker to Updater
Preparation runs separately from source analysis.
Scanner to Validated scanner cache
The scanner reads the selected validated data.
Updater to Validated scanner cache
The updater validates and selects a complete generation.
Job worker to Advisor connector
Advisor work receives an exact provider grant.
Advisor connector to Authorized Ollama provider
Only the authorized destination and request scope are used.
- The operator authorizes a narrow source root or supplies a supported bounded snapshot. Creating a project records its source identity; it does not grant access to another host directory.
- The control API checks the requested scope and current scanner preflight. It records the scan and a durable job together.
- The worker claims the job with a lease. The scanner validates source access again and runs the enabled tools against its captured source view and validated data generation.
- Native output becomes bounded, normalized, redacted findings. The worker validates the result manifest and pages, then commits admitted evidence and its recovery checkpoint to PostgreSQL.
- Only after that commit does the worker acknowledge the exact scanner result so temporary output can be removed. Complete evidence can then be evaluated against the project gate policy.
- Clients refresh authoritative resources as jobs and findings change. Optional advice and human dispositions are separate actions; neither supplies missing scanner coverage.
The jobs and evidence chapter follows the failure and recovery paths around these steps.
Put authority at each boundary
The core Compose setup exposes one loopback address through an unprivileged TCP relay. The relay forwards to the API and has no persistent mounts or runtime-secret configuration. The API has no Docker socket. Browser sessions and scoped editor capabilities enter through the same control boundary, with different authentication rules.
| Component | Reads and writes | Role in the flow |
|---|---|---|
| Control API | PostgreSQL, bounded source snapshots and admitted artifacts | Authorizes commands, serves resources and records durable state. It has no mounted project source. |
| Job worker | PostgreSQL and artifact storage; snapshots read-only | Owns execution, leases, progress, cancellation and result persistence. |
| Scanner | Authorized source, snapshots and validated cache read-only; private scratch and artifact output | Executes the selected pinned tools and publishes a bounded result protocol. |
| Scanner-data updater | Scanner cache writable; reviewed download sources | Prepares and activates complete data generations without a project-source mount. |
| Advisor connector | Dedicated provider authorization and approved provider routes | Performs narrowly granted local or remote Ollama work. It has no project-source mount. |
The scanner uses an internal network. The updater and Advisor connector have separate egress networks. The worker calls the Advisor connector for both local and remote model requests; it does not send prompts directly to Ollama. These are source-defined deployment boundaries. Image contents, effective mounts and actual egress still need verification for the installation being assessed.
See source and client authority for the decisions behind these boundaries and internal services for their protocols.
Keep different kinds of state separate
| Question | Authoritative state | What it does not imply |
|---|---|---|
| Was the command accepted? | Durable job and command identity | That execution started or succeeded. |
| Is the scan complete? | Scan status, tool outcomes and coverage summary | That every possible vulnerability was checked. |
| How was a finding reviewed? | Finding disposition, reason and revision | That an edited file was verified or a new scan inherits the decision. |
| Does the evidence meet policy? | Gate decision for complete scan evidence | That repository protection is installed or a push is authorized. |
| May this protected push proceed? | Current repository authority, outgoing trees, scanner evidence and policy | That a local hook cannot be bypassed. |
This separation makes an incomplete scan visible even when its collected findings have all been suppressed. It also prevents a working-tree pass from standing in for checks of earlier outgoing commits. Read findings, gates and Git protection for the operator workflows.
Understand what persists
PostgreSQL retains projects, scans, normalized findings, policies and jobs. Named volumes hold admitted artifacts, scanner data and source snapshots. Raw native reports and scanner transport spool have bounded temporary lifetimes. Opening or closing a browser page does not own the lifetime of a job.
This is a durable application design, not a disaster-recovery guarantee. The source documents an experimental, non-atomic backup helper that is disabled by default. A tested recovery procedure needs its own evidence and exact inputs.
Optional monitoring, local Git-proxy and database-administration profiles are off by default. They are not part of the core control API’s authority and do not make the workbench a hosted service.
Read the implementation by responsibility
| Source area | Start here |
|---|---|
| Services, mounts and networks | Compose configuration |
| Control application and persistence | API application, data model |
| Execution and scanner preparation | Scanning architecture |
| Browser and editor updates | Events and reconciliation |
| Contributor changes | Extension seams |
The security policy defines the trust assumptions. CodeSecurity is not a sandbox for hostile repositories. A passing gate is a policy result over admitted evidence, not a guarantee that code is secure.