195 lines
15 KiB
Markdown
195 lines
15 KiB
Markdown
<p align="center"><img src="docs/brand/safetynet-readme.png" alt="SafetyNet" width="620"></p>
|
|
|
|
# SafetyNet · S Browser
|
|
|
|
**A managed browser for enterprise AI work, with local content inspection and central security policy.**
|
|
|
|
> **UNDER HEAVY DEVELOPMENT** — SafetyNet is a Windows-first development prototype. It is not production-ready, independently security-audited, or certified. Current Windows builds are unsigned. Evaluate it with synthetic data in an isolated test environment.
|
|
|
|
SafetyNet combines an Electron/Chromium desktop browser, an administrator web console, a local document-inspection service, and a controlled AI gateway. Employees can use approved AI tools while administrators decide which information may leave the organization and where it may go.
|
|
|
|
S Browser uses translucent materials, rounded controls, light/dark themes, and a content-first layout inspired by Safari. Website content is left unchanged.
|
|
|
|
## A look inside
|
|
|
|
|
|
|
|
*Browser shell preview with synthetic bookmarks; this showcase is not a live external website.*
|
|
|
|
|
|
|
|
*Create your own named profiles and assign website access and feature permissions. This screenshot uses a synthetic test organization.*
|
|
|
|
|
|
|
|
*Local agents select centrally approved identities. Each identity has separate permissions, expiry and an encrypted pairing file.*
|
|
|
|
## What you can evaluate today
|
|
|
|
| Area | Current capabilities |
|
|
| --- | --- |
|
|
| Managed browsing | Independent native tabs, enrollment, device inventory, revocation, centrally controlled settings, themes, company bookmarks and personal-bookmark permissions. |
|
|
| User and device policies | Custom named profiles for verified SSO subjects or explicit devices; allowlists, blocklists, administrator-maintained domain categories, DevTools delegation, restrictive device groups and explicit pilot cohorts. |
|
|
| Local DLP | Secret detectors, document fingerprints, supported text/PDF/Office/image extraction, offline RapidOCR and optional EmbeddingGemma 2 semantic classification. Reference training retains derived features rather than complete source documents. |
|
|
| Transfers | Bounded pre-release download scanning, byte-derived file-type checks, SHA-256 binding, configurable YARA and company ICAP. Supported clipboard, in-memory request bodies and outgoing HTTP headers receive policy checks. Ordinary Windows NTFS file uploads use held native handles and pre-release inspection; unsupported ranges, data pipes and streams remain blocked. |
|
|
| Integrations | OIDC SSO; administrator/operator/auditor roles; system/fixed/PAC proxies; managed DNS; optional Windows VPN presence checks; ICAP/ICAPS inspection. |
|
|
| Administration | Policy templates, diffs and history, independent publication review, groups, profiles, teaching workflows, incidents and configurable event retention. |
|
|
| AI and agents | Approved AI routing with server-held credentials; scoped local agent navigation, tabs, page interaction, settings, bookmarks, inspected history and bounded browser window controls. Separate centrally approved agent identities, scoped credentials, expiry, generation rotation and targeted revocation; administrators can disable all agent access. |
|
|
| Observability | OpenTelemetry traces, metrics and sanitized logs; durable security events; ECS/CEF exports and HTTPS/mTLS SIEM delivery. Governed protected download metadata, completed clipboard/agent-click metadata and opt-in observed foreground clicks/form gestures. Full replay and content recording remain incomplete. |
|
|
| Additional controls | Local encrypted password vault with explicit autofill and separately approved agent status/masked inventory/fill after human unlock. Default-off controlled login preparation can authorize one approved native form POST; protected-brand visual similarity checks pair with trusted HTTPS origins. These features require further independent evaluation. |
|
|
|
|
Individual agent mode currently blocks browser-session requests without a known guarded tab owner, including unattributed background-worker traffic. Reliable agent ownership for these requests remains open. The browser does not assign an unattributed request to whichever tab happens to be foreground. See [individual agent administration](docs/individual-agent-grants.md) and [agent API](AGENT-API.md). Separately approved [saved sessions](docs/agent-session-controls.md) retain locally encrypted URL/title/group collections; restoration rechecks current policy and creates managed tabs without saving form or authentication state.
|
|
|
|
[Controlled vault login preparation](docs/controlled-credential-policy.md) is separate from ordinary autofill. Administrators approve exact HTTPS action URLs and credential field names; human unlock is required, and agents need the separate `vault:prepare-submit` capability. Preparation fills the form but does not submit it. Supported native same-origin URL-encoded POSTs remain subject to current policy and inspection of every other field; arbitrary JavaScript/XHR/JSON login flows remain unsupported. The approved site can read filled credentials in its DOM. This is not password isolation or proof of website identity.
|
|
|
|
Permissions are enforced by the backend and privileged browser code, not merely by hiding controls. Matching restrictive policies accumulate. Domain categories are curated company lists, not a subscription categorization feed.
|
|
|
|
Developer tools are a privileged exception, disabled for ordinary profiles. Delegating them changes the trust boundary: DevTools can provide paths outside normal clipboard guards. Grant access only to explicitly trusted developer profiles; do not assume complete DLP coverage when they are enabled.
|
|
|
|
## Architecture
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
Admin[Admin web console] --> Management[Management and signed policies]
|
|
Management --> Browser[S Browser · Electron/Chromium]
|
|
Browser --> Inspector[Local Windows AppContainer inspector]
|
|
Browser --> Gateway[Controlled AI gateway]
|
|
Gateway --> Models[Approved local or external models]
|
|
Browser --> Audit[Durable security events and SIEM]
|
|
Management --> Audit
|
|
Browser --> OTel[OpenTelemetry Collector]
|
|
Gateway --> OTel
|
|
```
|
|
|
|
Local parsing, OCR, YARA and semantic classification do not send documents to a public classification service. Configured ICAP and external AI services receive the selected content at the explicitly approved destination. Parser workers use a zero-capability Windows AppContainer; management and external integrations operate outside that parser boundary.
|
|
|
|
## Run a local evaluation
|
|
|
|
### Prerequisites
|
|
|
|
- Windows x64, the active development and test platform. macOS, Linux and mobile are future work.
|
|
- Node.js 24+ and npm.
|
|
- Python with `pip` for provisioning the pinned private Windows Python runtime and locked inspection dependencies.
|
|
- Disk space for dependencies and optional local models. Native semantic weights occupy approximately 865 MB before the worker and other runtime files.
|
|
|
|
There is no downloadable signed installer or self-contained semantic-model bootstrap in this repository. Weights, private runtimes and generated builds are excluded from source control. Provisioning needs network access; normal local inspection does not download models.
|
|
|
|
### 1. Install and initialize
|
|
|
|
```powershell
|
|
git clone https://tea.karlcom.de/karl/safetynet.git
|
|
cd safetynet
|
|
npm ci
|
|
node node_modules/electron/install.js
|
|
npm run init
|
|
npm run runtime:win
|
|
```
|
|
|
|
`npm run init` creates `.env` from `.env.example` and generates private administrator and inspector credentials. It preserves existing configuration. Keep `.env` private and never commit it.
|
|
|
|
For a **single-administrator HTTP loopback demo only**, set this in `.env`:
|
|
|
|
```dotenv
|
|
REQUIRE_INDEPENDENT_POLICY_APPROVAL=false
|
|
```
|
|
|
|
Independent review is enabled in the example by default. Keep it enabled for enterprise evaluation with two different SSO administrator identities: a shared development token cannot provide an independent reviewer.
|
|
|
|
### 2. Start the services
|
|
|
|
Run each command in a separate terminal from the repository root:
|
|
|
|
```powershell
|
|
npm run inspector
|
|
```
|
|
|
|
```powershell
|
|
npm run server
|
|
```
|
|
|
|
Open **http://127.0.0.1:4310**. For the demo, enter `ADMIN_TOKEN` from your private `.env` in the console. For enterprise access, configure OIDC and use your identity provider.
|
|
|
|
```powershell
|
|
npm run browser
|
|
```
|
|
|
|
Create a one-use enrollment code in the console, then enroll the browser against the management server. Browser SSO enrollment is also supported when configured. Browsing remains locked until enrollment and a valid policy refresh complete. Revocation, expired policy or management failure pauses browsing.
|
|
|
|
### 3. Try the management workflow
|
|
|
|
1. Start from a policy template and review changes before publishing.
|
|
2. Add company bookmarks and configure employee-edit permissions.
|
|
3. Create a named profile, assign devices or verified SSO subjects, and set website and DevTools permissions.
|
|
4. Register a synthetic confidential reference document, review inspection coverage, and publish its derived rules.
|
|
5. Test allowed and blocked actions, then inspect security events and incident records.
|
|
6. Use a pilot cohort before expanding a policy. When independent review is enabled, a different administrator approves publication.
|
|
|
|
Mandatory scanners fail closed when unavailable. Disabling YARA does not silently disable other mandatory inspection. Test required proxy, VPN, DNS and ICAP reachability before rolling out their policies.
|
|
|
|
### Optional offline semantic classification
|
|
|
|
The EmbeddingGemma 2 provisioner currently imports a verified distribution from a separately prepared compatible source project. It does not download arbitrary model weights or accept an unverified replacement.
|
|
|
|
```powershell
|
|
python scripts/provision-semantic-runtime.py --source-project C:/path/to/compatible-source-project
|
|
python scripts/provision-semantic-runtime.py --verify
|
|
npm run runtime:win
|
|
```
|
|
|
|
The source layout and pinned hashes are defined in [the provisioner](scripts/provision-semantic-runtime.py). Without that distribution, keep semantic classification disabled; other provisioned local inspection can be evaluated. A standalone model/runtime installation workflow remains open. Reprovision ACLs after changing inspector or model files; see [Windows installation prerequisites](docs/windows-appcontainer-installation.md).
|
|
|
|
## Enterprise configuration
|
|
|
|
The console is a separate web application. Deploy it behind trusted HTTPS with OIDC, a protected service identity and restricted database/key access. Remote management does not accept the shared loopback development token.
|
|
|
|
Use `.env.example` as the configuration reference for OIDC, inspector authentication, AI, OpenTelemetry, SIEM and optional protected evidence. Provision secrets through your deployment secret manager, not browser-editable settings or source control. No Docker-based production deployment is supplied.
|
|
|
|
Policies have signed versions, expiry checks, device binding and rollback protection. The protected rollout channel uses ML-KEM-1024, AES-256-GCM and authenticated ML-DSA-87/Ed25519 challenges in addition to HTTPS. Initial trust, signing-key custody, rotation and independent cryptographic review remain deployment work; this is not FIPS validation or a guarantee of complete quantum security.
|
|
|
|
Further guidance:
|
|
|
|
- [Admin access, SSO and roles](docs/admin-security.md) and [deployment model](deploy/ADMIN-MANAGEMENT.md)
|
|
- [Independent policy approval](docs/policy-review.md)
|
|
- [Custom profiles](docs/user-profile-policies.md) and [pilot rollouts](docs/group-policy-rollout.md)
|
|
- [Transfer type and scanner controls](docs/file-transfer-controls.md)
|
|
- [Local agent API](AGENT-API.md) and [browser diagnostics](docs/browser-diagnostics.md)
|
|
- [Incidents](docs/incident-management.md), [event retention](docs/audit-retention.md) and [protected evidence](docs/protected-evidence.md)
|
|
|
|
## Verify and build
|
|
|
|
```powershell
|
|
npm test
|
|
npm run check
|
|
.runtime/windows/python/python.exe -m unittest discover -s apps/inspector -p "test_*.py"
|
|
npm run smoke
|
|
npm run preview:ui
|
|
```
|
|
|
|
Native tests use controlled receivers and an isolated browser profile. Clipboard tests use the Windows clipboard; run them serially. Passing tests establish the exercised scenarios, rather than universal prevention coverage.
|
|
|
|
After provisioning the semantic distribution and private Windows runtime:
|
|
|
|
```powershell
|
|
npm run package:win
|
|
npm run verify:package
|
|
```
|
|
|
|
The packaging workflow produces an unpacked evaluation build in `dist/win-unpacked`. Distribute the complete folder, not the executable alone. Code signing, a production installer and a trusted update service remain unfinished.
|
|
|
|
## Current boundaries
|
|
|
|
An Electron shell does not yet provide complete enterprise DLP across every transport. [Ordinary Windows NTFS file uploads](docs/windows-file-uploads.md) have a tested handle-bound release path; unsupported ranges, reparse/network paths, data pipes and upload redirects remain blocked. WebSocket/WebRTC/streaming, encoded or covert channels, printing, OS screen capture, other applications and local administrator tampering are not fully covered. Complete audio/video transcription and frame coverage are unfinished.
|
|
|
|
Full forensic browser replay, a complete analyst evidence interface, executable/device cryptographic identity, SCIM, production key rotation, tested backup/recovery and independent security testing remain open. Separate agent credentials and bounded metadata capture are implemented; their Windows same-user trust boundary remains. An allow decision means no implemented rule matched the supported input; it does not guarantee absence of secrets or malware.
|
|
|
|
See the [threat model](docs/threat-model.md) and [requirements audit and roadmap](docs/requirements-audit.md) for coverage and remaining gates. Report security concerns privately to the repository owner; never post credentials or confidential documents in a public issue.
|
|
|
|
## Project and third-party licensing
|
|
|
|
A project distribution license has not yet been selected. Third-party components and weights retain their own terms; review them and complete redistribution notices before distributing a build.
|
|
|
|
|
|
Security audit verification, optional external ML-DSA-87 signing and retention proof details are documented in [Audit integrity](docs/audit-integrity.md). Independent checkpoint delivery and production signing-key rotation remain under development.
|
|
|
|
Centrally signed, default-off [automatic download evidence](docs/automatic-download-evidence.md) records protected file metadata without storing document bodies. [Interaction evidence](docs/interaction-evidence.md) covers completed guarded copy/cut/paste, agent clicks and observed foreground click/form gestures using bounded metadata. An observed form event does not prove transmission. Evidence upload uses a [dedicated PQ channel](docs/evidence-pq-channel.md); broader content/interaction capture, device identity and production key custody remain under development.
|