first commit
This commit is contained in:
Karl committed
commit
ff482ebe23
251 files changed
+19126
No files matched your search
@@ -0,0 +1,182 @@
|
||||
<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.*
|
||||
|
||||
## 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 and in-memory request paths receive policy checks. Unsupported native file/data-pipe uploads 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 and bookmarks. Administrators can disable agent access centrally. |
|
||||
| Observability | OpenTelemetry traces, metrics and sanitized logs; durable security events; ECS/CEF exports and HTTPS/mTLS SIEM delivery. An encrypted evidence server is implemented; automatic browser capture and analyst presentation remain incomplete. |
|
||||
| Additional controls | Local encrypted password vault with explicit autofill; protected-brand visual similarity checks paired with trusted HTTPS origins. These features require further independent evaluation. |
|
||||
|
||||
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. Native file/data-pipe uploads have no approved release path. 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.
|
||||
|
||||
Automatic forensic browser capture, a complete analyst evidence interface, per-agent cryptographic identities and replay-resistant request proofs, SCIM, production key rotation, tested backup/recovery and independent security testing remain open. 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.
|
||||
|
||||
Reference in new issue
Block a user