Skip to content

docs: publish an assertive repository overview #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Litju merged 1 commit into from
Aug 17, 2026
Merged

docs: publish an assertive repository overview #17

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 101 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,86 @@
# SecScanMonitor

SecScanMonitor is an agentic cybersecurity firm for agents. It inspects code, policy, evidence paths, and architecture; records findings with provenance; and reports what is confirmed, what is uncertain, and what is not validated.
[![CI](https://github.com/Litju/Sec-Scan-Monitor/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Litju/Sec-Scan-Monitor/actions/workflows/ci.yml)
[![CodeQL](https://github.com/Litju/Sec-Scan-Monitor/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/Litju/Sec-Scan-Monitor/actions/workflows/codeql.yml)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/Litju/Sec-Scan-Monitor/badge)](https://securityscorecards.dev/viewer/?uri=github.com/Litju/Sec-Scan-Monitor)
[![License](https://img.shields.io/badge/license-Apache--2.0-91a995.svg)](LICENSE)

This repository is the public foundation of the SecScanMonitor platform. It is an inspection-first, advisory product for agent-built systems. It does not silently mutate targets, expose raw evidence, handle live credentials, or turn an unverified signal into a finding.
<p align="center">
<img src="apps/web/app/icon.svg" alt="SecScanMonitor product mark" width="128">
</p>

## What is here
> **SecScanMonitor is an evidence-first cybersecurity operating system for AI agents.**

- A typed platform core for engagements, authority, capabilities, evidence, observations, claims, adjudication, and findings.
- A localhost-first API and read-only product surface with synthetic preview data.
- Deterministic policy, sandbox, evidence, and report boundaries.
- A synthetic inspection example and tests for the public behavior.
It turns a contracted inspection into a bounded, traceable, advisory result. The platform inspects code, policy, architecture, authority, and evidence paths; preserves provenance; separates observations from conclusions; and states clearly what is confirmed, uncertain, inconclusive, or not validated.

The public tree does not contain client material, engagement reports, evidence exports, ledgers, recovery material, private configuration, or historical private repository history.
This is both a cybersecurity firm model and its working platform foundation. It is built for agent-created systems that need security decisions they can audit—not opaque scans, silent mutations, or confident guesses.

## State labels
## What it does

Documentation uses these labels deliberately:
SecScanMonitor gives every engagement an explicit operating boundary:

- `IMPLEMENTED` — represented by code and covered by a public test or a repeatable local check.
- `QUALIFIED` — exercised by an explicit qualification run with retained evidence.
- `EXPERIMENTAL` — available for inspection or local experimentation, not a service guarantee.
- `PLANNED` — described direction, not an available capability.
- `NOT YET QUALIFIED` — the boundary exists but the required integration or evidence is absent.
- `NOT_VALIDATED` — no evidence was collected for the claim.
- **Contract first:** scope, pass type, authority, constraints, and evidence expectations are defined before work begins.
- **Inspection by default:** agents can inspect permitted targets, but they do not silently mutate them or bypass the authority model.
- **Evidence before findings:** the canonical chain is `EvidenceObject → Observation → Claim → Adjudication → Finding`.
- **Provenance throughout:** findings carry evidence references, rationale, severity, remediation guidance, verification steps, and confidence.
- **Honest uncertainty:** missing evidence produces an explicit `INCONCLUSIVE`, `NOT_VALIDATED`, or refusal-to-infer state.
- **Safe public foundation:** the public tree contains synthetic fixtures and metadata boundaries—not client material, raw evidence, recovery material, credentials, or private repository history.

## At a glance

| Area | Public foundation |
| --- | --- |
| Mission | Evidence-grounded cybersecurity review for agent-built systems |
| Operating model | Advisory-first, contract-bound, inspection-only by default |
| Product surface | Local/self-hosted API and a read-only synthetic preview UI |
| Decision path | Evidence → observation → claim → adjudication → finding |
| Current boundary | Local qualification foundation; hosted production is not validated |
| License | Apache License 2.0 |

## How the evidence path works

```mermaid
flowchart LR
accTitle: SecScanMonitor evidence-to-finding path
accDescr: A contracted inspection moves through authority, bounded evidence, and adjudication before it becomes an advisory finding.

contract["Engagement contract"] --> authority["Authority and policy"]
authority --> inspection["Bounded inspection"]
inspection --> evidence["Evidence metadata"]
evidence --> observation["Observation"]
observation --> claim["Claim"]
claim --> adjudication["Adjudication"]
adjudication --> finding["Finding and advisory report"]
```

Agents do not construct findings directly. Adjudication is the control point that keeps evidence, rationale, severity, confidence, remediation, and verification together. When the chain is incomplete, the platform preserves the limitation instead of inventing a conclusion.

## What is in the repository

| Path | Role |
| --- | --- |
| [`analysis/`](analysis/) | Typed platform core: engagements, authority, capabilities, evidence, observations, claims, adjudication, findings, policy, and reports |
| [`apps/web/`](apps/web/) | Desktop-first, read-only product surface with explicit preview and unavailable states |
| [`contracts/`](contracts/) | Engagement protocol, brigade contracts, and JSON schemas |
| [`docs/`](docs/) | Architecture decisions, security model, evidence handling, development, deployment, and roadmap |
| [`examples/`](examples/) | Synthetic inspection engagement and evidence fixtures |
| [`templates/`](templates/) | Change, engagement, incident, validation, and reporting templates |

## Current capabilities

- Typed engagement and authority boundaries.
- Capability manifests with risk, approval, sandbox, network, timeout, and resource constraints.
- Metadata-first evidence handling with content-addressed references and sanitization state.
- Deterministic policy and sandbox boundaries.
- Evidence-backed adjudication and advisory report structure.
- Scientific-integrity lineage surfaces that keep security findings separate from unsupported scientific conclusions.
- A local API and synthetic read-only web preview for exploring the model.

## Local development
The current public foundation is intentionally narrow. Managed hosted deployment, external identity providers, production Temporal operation, production object storage, and live-model execution remain `NOT YET QUALIFIED` here.

The supported public mode is local/self-hosted development. Managed cloud operation, multi-tenant production operation, and external service integrations are `NOT_VALIDATED` here.
## Run it locally

### Platform core

```bash
cd analysis
Expand All @@ -37,7 +91,7 @@ python -m mypy src
python -m ruff check src tests
```

The web surface is independent and synthetic by default:
### Web surface

```bash
cd apps/web
Expand All @@ -48,14 +102,38 @@ npm run lint
npm run build
```

See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the full local loop and [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for the explicit limits of self-hosted operation.
The web application runs in `PREVIEW` mode with synthetic, non-personal, non-client data. Local API integration is explicit:

```text
NEXT_PUBLIC_SECSCAN_MODE=LOCAL_INTEGRATED
SECSCAN_API_URL=http://127.0.0.1:8000
```

Read [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the complete local loop and [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for the limits of self-hosted operation.

## Security and authority
## Security and governance

Read [SECURITY.md](SECURITY.md) before reporting a vulnerability. Read [docs/SECURITY_MODEL.md](docs/SECURITY_MODEL.md), [docs/AGENT_AUTHORITY_MODEL.md](docs/AGENT_AUTHORITY_MODEL.md), and [docs/EVIDENCE_AND_ADJUDICATION.md](docs/EVIDENCE_AND_ADJUDICATION.md) before changing load-bearing boundaries.
This project treats authority and evidence as security controls. Read [SECURITY.md](SECURITY.md) before reporting a vulnerability, then review the [security model](docs/SECURITY_MODEL.md), [agent authority model](docs/AGENT_AUTHORITY_MODEL.md), and [evidence and adjudication model](docs/EVIDENCE_AND_ADJUDICATION.md) before changing a load-bearing boundary.

The public release is deliberately sanitized and allowlisted. It does not publish client reports, raw evidence, private ledgers, recovery material, live credentials, or private repository history.

## State labels

Every engagement requires a contract. Inspection-only is the default. A specialist may emit observations and claims; only adjudication may create a finding. Missing evidence produces an explicit uncertainty or `NOT_VALIDATED` state.
The documentation uses these labels precisely:

- `IMPLEMENTED` — represented by code and covered by a public test or repeatable local check.
- `QUALIFIED` — exercised by an explicit qualification run with retained evidence.
- `EXPERIMENTAL` — available for inspection or local experimentation, not a service guarantee.
- `PLANNED` — direction, not an available capability.
- `NOT YET QUALIFIED` — the boundary exists, but required integration or evidence is absent.
- `NOT VALIDATED` — no evidence was collected for the claim.

## License

SecScanMonitor is released under the Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

## What comes next

The foundation is intentionally inspectable and narrow today. The roadmap includes repeatable public dogfood, deeper adapter qualification, hosted identity and storage qualification, operational telemetry, and additional bounded service workflows.

There are many features to come, while the evidence, authority, and no-secrets boundaries remain non-negotiable.
Loading