Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,7 @@ jobs:
node --check preload.cjs
node --test backend-shutdown.test.cjs
node --test ui-entry.test.cjs
node --test candidate-profile.test.cjs
npx electron --version
- name: Build and stage packaged backend
run: |
Expand Down
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@

### Added

- Isolated Windows candidate builder with fresh packaged backend, short artifact
paths, separate metadata-only profile and bounded build/live-test storage.
A local 122-second packaged UI run reconciled 10,189 accepted/acknowledged/stored
packets; complete VPN-return and multi-hour acceptance remain open gates.
- Source-built experimental desktop entry with canonical components, a shared
controller and stable API identity. Retired compiled-bundle patching; isolated
Electron and desktop/mobile fixture checks cover navigation and selection.
Expand Down
32 changes: 32 additions & 0 deletions desktop/electron/candidate-main.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
const { app } = require('electron');
const fs = require('node:fs');
const path = require('node:path');
const net = require('node:net');
const { candidateEnvironment, candidatePort } = require('./candidate-profile.cjs');

const profile = process.env.NETBOT_CANDIDATE_PROFILE || path.join(app.getPath('appData'), 'netbot-candidate-preview');
Object.assign(process.env, candidateEnvironment(profile));
// Candidate packages must not silently run an inherited, older backend or dev URL.
delete process.env.NETBOT_BACKEND_BIN;
delete process.env.NETBOT_PYTHON_BIN;
delete process.env.NETBOT_DESKTOP_DEV_SERVER_URL;
app.setPath('userData', profile);
app.setName('NetBotPro Candidate');
const config = path.join(profile, 'config');
fs.mkdirSync(config, { recursive: true });
const settings = path.join(config, 'settings.json');
if (!fs.existsSync(settings)) {
fs.writeFileSync(settings, JSON.stringify({ iface: 'iface=default', autostart_sniffer: false,
auto_block: false, persist_logs: true, retention_minutes: 15, sniffer_sample_rate: 1,
payload_capture_enabled: false, capture_mode: 'metadata' }));
}
// Resolve a loopback port before main.cjs snapshots its backend configuration.
const reservation = net.createServer();
reservation.on('error', error => { throw error; });
reservation.listen(candidatePort(process.env.NETBOT_CANDIDATE_PORT), '127.0.0.1', () => {
const port = reservation.address().port;
reservation.close(() => {
process.env.NETBOT_PORT = String(port);
require('./main.cjs');
});
});
24 changes: 24 additions & 0 deletions desktop/electron/candidate-profile.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
const path = require('node:path');

function candidateEnvironment(profile) {
if (!path.isAbsolute(profile) || !path.basename(profile).startsWith('netbot-candidate-')) {
throw new Error('Candidate profile must be an absolute, explicitly named netbot-candidate-* directory');
}
return {
NETBOT_DESKTOP_UI: 'desktop', NETBOT_CAPTURE_MODE: 'metadata', NETBOT_HOST: '127.0.0.1', NETBOT_PROFILE: 'desktop',
NETBOT_CAPTURE_PROCESS: '1', NETBOT_CAPTURE_JOURNAL: '1', NETBOT_JOURNAL_ACK_MODE: 'history',
NETBOT_PAYLOAD_CAPTURE: '0', NETBOT_ALLOW_FULL_CAPTURE: '0', NETBOT_REDACT_SENSITIVE_DATA: '1',
NETBOT_STABILITY_RECORDING: '0', NETBOT_PROFILE_STAGES: '0',
NETBOT_DB_PATH: path.join(profile, 'data', 'history.db'),
NETBOT_FLOW_DB_PATH: path.join(profile, 'data', 'flows.db'),
NETBOT_CAPTURE_JOURNAL_PATH: path.join(profile, 'data', 'journal.db'),
NETBOT_RUNTIME_DIR: path.join(profile, 'runtime'), NETBOT_CACHE_DIR: path.join(profile, 'cache'),
};
}
function candidatePort(value) {
if (value === undefined || value === '') return 0;
const port = Number(value);
if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Invalid candidate port');
return port;
}
module.exports = { candidateEnvironment, candidatePort };
26 changes: 26 additions & 0 deletions desktop/electron/candidate-profile.test.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
const { test } = require('node:test');
const assert = require('node:assert/strict');
const path = require('node:path');
const { candidateEnvironment, candidatePort } = require('./candidate-profile.cjs');

test('candidate storage paths stay in its dedicated profile', () => {
const root = path.resolve('netbot-candidate-fixture');
const env = candidateEnvironment(root);
for (const [key, value] of Object.entries(env)) {
if (key.endsWith('_PATH') || key.endsWith('_DIR')) assert.ok(value.startsWith(root + path.sep));
}
assert.equal(env.NETBOT_JOURNAL_ACK_MODE, 'history');
assert.equal(env.NETBOT_CAPTURE_MODE, 'metadata');
assert.equal(env.NETBOT_STABILITY_RECORDING, '0');
});
test('candidate rejects relative and ordinary installed profiles', () => {
for (const value of ['netbot-candidate-fixture', path.resolve('Netbotpro'), path.parse(process.cwd()).root]) {
assert.throws(() => candidateEnvironment(value));
}
});
test('candidate port defaults to ephemeral and validates explicit requests', () => {
assert.equal(candidatePort(), 0);
assert.equal(candidatePort(''), 0);
assert.equal(candidatePort('49152'), 49152);
for (const value of ['0', '-1', '65536', '8765/path', '1.5']) assert.throws(() => candidatePort(value));
});
127 changes: 127 additions & 0 deletions docs/DESKTOP_CANDIDATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# Isolated Windows Desktop Candidate

This is a validation package, not an installed-app replacement or a release.
The normal Electron entry and installed profile are unchanged.

## Build

Install the repository's Python, frontend and desktop dependencies first, then
commit source changes so the candidate has an unambiguous source revision:

```powershell
python scripts/release/build_desktop_candidate.py
```

The builder creates a new revision/timestamp directory under
`%LOCALAPPDATA%/NetBotCandidates/` (a short path avoids legacy Windows path limits
inside scientific-library bundles). It packages a fresh PyInstaller backend and both
Vite entries, then builds an unpacked Electron candidate. It never copies the old
security-build backend or stages over `packaging/runtime/backend` or an installed
app. `candidate.json` records its source revision and executable path. Build
dependencies must already exist; the builder does not install global software.

Build steps have 15-minute deadlines and a sampled 3 GiB workspace budget.
Starting requires 5 GiB free space, and the build stops below 2 GiB free. Sampling
can overshoot briefly. Failed artifacts are retained for diagnosis, not deleted
automatically. New builds are refused once retained candidate artifacts exceed
2 GiB, preventing repeated test builds from accumulating indefinitely. A newly
admitted build can still add up to its own sampled 3 GiB budget. Existing artifacts
are not silently deleted; review their ownership before any manual cleanup.

## Candidate Profile

The candidate bootstrap selects `desktop.html`, sets its own user-data directory,
and overrides history, flow, journal, cache and runtime paths within that profile.
It rejects ordinary profile paths and inherited backend/dev-server overrides.
It chooses a free loopback API port rather than inheriting the standard app's
port; tests can explicitly reserve one with `NETBOT_CANDIDATE_PORT`. There is a
small release-to-backend-bind race, so an unlikely startup collision remains
possible. The profile and generated local authentication token remain separate.
The default is `%APPDATA%/netbot-candidate-preview`; tests explicitly use a new
`netbot-candidate-smoke-*` temporary profile instead.

New profiles start with metadata-only capture, auto-block and autostart disabled,
15-minute metadata retention and sampling rate one. Candidate history-confirmed
journaling is explicitly enabled. This does not change installed/default capture
policy or establish exactly-once analysis. The candidate is not a production soak
configuration or a hard disk quota.

## Explicit Live Test

```powershell
$env:NETBOT_CANDIDATE_EXE = '<absolute executable path from candidate.json>'
$env:NETBOT_SMOKE_PYTHON_BIN = '<absolute Python executable>'
$env:NETBOT_CANDIDATE_DURATION = '60'
node frontend/desktop-reference/test-candidate-capture.mjs
```

This starts real capture through the candidate's UI. Run only on a network you
are authorized to inspect and with a working Npcap driver. It does not change VPN,
routes, firewall rules or generate test traffic. Duration is restricted to 15..120
seconds, with a sampled 128 MiB temporary-profile budget. It exercises packet
selection, investigation, Auto-follow and Stop, then verifies acknowledged history
against SQLite rows after a normal acknowledged app shutdown.

Only numeric counters are printed. Raw traffic screenshots, domains and packet
records are not exported. The temporary test profile is removed after the test;
an emergency deadline can terminate only the owned candidate process tree. This
test fixture's data is disposable, unlike an installed recovery journal.

An interface-change count does not prove a complete VPN-return scenario. Such a
scenario requires an actual user-approved route change while capture is active.
Missing driver statistics remain unknown, not proof of zero wire loss. A short
successful capture does not establish multi-hour stability.

## Local Evidence: 2026-11-12

The independently built candidate used source revision
`a9512a398dde95622ed7c7ae5b2db18669e45023`, a fresh packaged backend and Electron
45.2.3. The complete build workspace, including intermediate files, was
857,832,152 bytes. An initial long-checkout build exposed a Windows path-length
failure while copying a scientific-library binary; the short candidate root
resolved it without changing OS settings or using an old packaged backend.

The final live run used the improved page-aware test harness:

| Observation | Measured |
| --- | ---: |
| Capture plus UI checks | 122 seconds |
| Accepted / acknowledged / SQLite packet rows | 10,189 / 10,189 / 10,189 |
| Final journal pending | 0 |
| Sampled peak pending | 128 |
| Failed / dropped history writes | 0 / 0 |
| Reported driver buffer drops | 0; final statistics coverage complete |
| Renderer errors | 0 |
| Sampled local API p95 | 40 ms |
| Packet selection through investigation findings | 175 ms |
| Stop completion | 473 ms |
| Sampled temporary profile peak | 28,535,468 bytes |
| Acknowledged app shutdown and temporary-profile removal | Passed |

These API and selection samples include test overhead and are not controlled
throughput/latency benchmarks. Memory/CPU and multi-hour growth still need
dedicated profiling. Driver counters do not prove zero wire loss.

In a separate 22-second run with one observed interface change, all 1,170
accepted packets were acknowledged and stored, final pending was zero, and UI
checks passed. A longer transition observation recorded two interface switches
with positive progressing capture counters, but its UI check failed because the
test assumed Live Monitor stayed selected while another page was active.
The harness now explicitly navigates back before selecting a packet and records
the active page with numeric samples. That failed UI assertion is not counted as
a successful complete VPN-return acceptance run. The final 122-second run had
no interface changes, so it does not close the full VPN-return/long-soak gate.

No installed application or installed profile was replaced. Only numeric
summaries were exported; real traffic screenshots and raw records were not kept.

The subsequent candidate from revision
`8a3c459b7734ef05e30dcfb2d9b864a0c9c505c2` also passed a 31-second real capture
with a deliberately occupied inherited API port. Its bootstrap chose another
loopback port, and all 11,705 packets were accepted, acknowledged and stored.
Final pending was zero, sampled peak pending was 3,533, history failures/drops
and renderer errors were zero, and final driver coverage reported zero buffer
drops. Sampled API p95 was 51 ms, selection/investigation 218 ms, Stop 584 ms,
and temporary profile peak 26,005,043 bytes. The larger transient backlog is
retained as an observation, not described as zero queue pressure. This run had
no interface switch and does not close the full VPN-return gate.
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ describe their own release, not the current branch or installed desktop overlay.
- [Validation and CPU measurement](VALIDATION.md)
- [Isolated journal/history probe and local evidence](JOURNAL_HISTORY_PROBE.md)
- [Standard frontend live-follow continuity](LIVE_FOLLOW_VALIDATION.md)
- [Isolated Windows desktop candidate](DESKTOP_CANDIDATE.md)
- [Screenshot provenance](SCREENSHOTS.md)
- [Repository and GitHub maintenance](REPOSITORY_MAINTENANCE.md)

Expand Down
Loading
Loading