9.2 KiB
Resource compatibility planner and isolated qualifier
This is a proposal-only P0 slice. plan never changes runtime or config.
Explicit isolated qualification temporarily installs an owned NFQ worker and
queue rules, but never changes legacy SQL groups, renderer or apply journals.
Monitor HEALTHY, old SQL measurements and public check JSON are not proof.
Without a completed owned qualification batch, compatibility is UNKNOWN and
hosts are unassigned. No PASS/evidence import is exposed.
Commands require root and the existing managed-test target settings:
zapret-autotune strategy-import --strategies /private/strategies.json
zapret-autotune plan --config /private/resources.json
zapret-autotune qualify --config /private/resources.json --strategies /private/strategies.json --isolated
strategy-import requires an owned, regular, single-link 0600 file. Only
definitions are accepted; duplicate keys, unknown fields and evidence fields
are rejected. Example:
{
"version": 1,
"strategies": [
{
"id": "split-one",
"args": "--payload=tls_client_hello --lua-desync=multisplit:pos=1",
"selectors": {"transport":"tcp","ports":"443","l7":"tls","tls":"both"}
}
]
}
The registry is one immutable batch (1–32 unique IDs). This conservative slice
accepts only TCP/443/TLS selectors and tls12, tls13, or both policy.
Argument whitespace is canonicalized; option/Lua stage order is preserved.
Existing payload/range validation is reused. Lua stages are restricted to
fake, multisplit, multidisorder, fakeddisorder, split and disorder; parameters
to pos, repeats, tcp_ts, tcp_flags_set, seqovl and blob=fake_default_tls.
File/inline Lua, queue/user/fwmark/filter options and arbitrary stages are
rejected. Acceptance of a definition is not runtime verification.
The private target directory holds .resource-plan-key (32 random bytes),
.resource-plan-strategies.json and, when an owned producer exists,
.resource-plan-matrix.json. JSON envelopes have payload and an HMAC-SHA256
mac. Each file is write-once, owned, 0600, no-follow, single-link and bounded
to 64 KiB. Held directory/file identities and exact snapshots are checked;
foreign entries, replacement inodes and modified bytes are never clobbered or
silently adopted. Interrupted writes remain blocked for explicit operator
repair. There is no automatic rotation/update/repair in this slice. The private
key and same-UID/root boundary must be protected: HMAC is not protection from an
actor who can read the key and replace the whole target state between processes.
Matrix v1 binds the registry digest and at most one completed run per candidate. Each run binds ID, definition digest (canonical args and selectors), keyed config fingerprint, start/completion milliseconds, resource/TLS outcomes and keyed resource fingerprints. Its attestation records collector/runtime, definition digest, composite executable/Lua input hash, installed rules hash, actual worker-argv hash, queue and worker PID/start identity, plus restored/joined completion. No URLs, headers, resolved IPs, bodies or raw errors are persisted. A nonserialized producer seal protects the completed in-memory snapshot against mutation before publication. Only the owned producer and test-internal fixtures create seals; JSON DTOs cannot authorize publication. Every resource/protocol cell records exactly three actual attempts; any nonpass in those attempts makes the cell negative (never an average or partial PASS).
plan loads only authenticated private state and the existing resource-config
snapshot (including resolved environment secrets, DNS/proxy and private headers
in keyed fingerprints). Every resource on an exact host, across all services
and input group labels, must have matching complete results for every required
TLS protocol. Complete failed checks are negative; missing, expired (24 hours),
future, mismatched or partial checks are unknown. Changed config invalidates old
run evidence. Malformed/unauthenticated state yields blocked, unassigned output
and exit 78; valid missing evidence yields unknown output and exit 0.
Output contains proposal_only, evidence (authentication status, not
health), per-host validated/negative/unknown candidate alternatives,
assignments and unassigned. Compatible equal args/selectors merge coverage
across input labels. Greedy greatest-uncovered coverage, then lexical candidate
ID, produces deterministic disjoint exact-host assignments. It does not claim
global optimality or suffix coverage. Explicit legacy YouTube suffix policy is
unchanged.
INTRUSIVE / ISOLATED startup only
Set both ZAPRET_AUTOTUNE_QUALIFY_CONFIG and
ZAPRET_AUTOTUNE_STRATEGY_CONFIG to container paths on a dedicated target.
Do not send working user traffic to this target's published SOCKS port. This is
not noninterrupting background search. Provision the private resource and 0600
strategy files separately; compose forwards paths but does not mount files for
you. Start with the managed disabled baseline, not an existing active profile.
Qualification v1 accepts lowercase DNS hostnames, not literal IP targets; the
ordinary resource-check command's broader literal-IP policy is unchanged.
PID 1 starts its owned SS+DoH services, initializes/reconciles known state, then
launches one finite qualify ... --isolated session instead of starting the
live zapret daemon or monitor. Qualifier checks root/target namespace, PID 1's
actual entrypoint/environment, direct-child executable/arguments/session ACK,
owned SS and DNS readiness anchors. A flag or docker-exec environment alone
does not authorize qualification. Missing either startup path fails closed.
Without --isolated, qualify remains UNKNOWN/exit 78 without runtime changes.
The shared monitor singleton excludes legacy and generic controllers. Any existing NFQ worker/queue, active profile, unknown config/journal or existing immutable matrix is refused. Known baseline config/journal/backup/identity inodes and bytes remain held unchanged throughout the job. This first producer does not pause/stop/restart existing active profiles; job-bound maintenance rollback is deferred rather than pretending a path-only daemon stop is safe.
Each candidate uses the existing worker-before-nft/queue-ready lifecycle on
queue 200, fixed Lua imports and fwmark 0x10000000, plus native
--filter-l7=tls. The actual child executable, argv, parent, start identity,
queue socket ownership, executable/Lua hashes, native --version output 1.0.2
and installed nft rule bytes are attested before capture and checked again at
each collector guard. DoH's existing 0x50000000 socket mark bypass remains.
TLS policy is collector/eligibility policy, not a nonexistent native TLS-version
filter. All configured protocols are measured; incompatible selector policies
remain UNKNOWN in the proposal.
The existing GET/HEAD generic collector preserves TLS origin verification, configured body/status/content-type expectations, private stdin and IP pinning. Completed expectation failures and typed peer response/TLS/transport negatives do not stop the remaining repeats/cells. Guard/source/unknown infrastructure or batch cancellation veto the entire batch; no partial positive matrix is saved. Config (including resolved environment/header secrets) and strategy-source snapshots are checked after DNS/before transfer and before sealing/publication. Workers are joined and temporary nft queues removed before verifying unchanged disabled baseline/runtime and sealing. The batch has a fixed 15-minute deadline with separate bounded cleanup; PID 1 keeps SS+DoH alive through cleanup. The bounded 64 KiB matrix size (including its authenticated envelope and worst-case field widths) is checked before any worker/nft operation; excessive catalogue/resource combinations return UNKNOWN/exit 64 even within individual count caps (32 strategies, 64 resources).
Successful batches, including complete negatives, return the assignment proposal. Incomplete/unsafe jobs return UNKNOWN/blocked exit 78 without proof. PID 1 then stays safe-idle with SS+DoH for inspection, for either success or blocked completion: no qualification retry loop, duplicate controller or automatic generic monitor start. Retests require future explicit immutable snapshot rotation, not overwriting prior evidence.
Completed controller cleanup is acknowledged separately from qualification in
an exclusive, 0600 HMAC-authenticated qualification-completed.json on the
current boot's SS tmpfs. It binds the launched PID, exit outcome (0 or 78) and
verified cleanup; it is not strategy proof. PID 1 checks that ACK against its
private session launch and revalidates the disabled baseline, singleton,
SS/DoH ownership and absence of NFQ workers/temporary nft queues before shutting
down dependencies. Thus TERM after a clean blocked qualifier has exited but
before its parent reaps it can exit cleanly. Worker/nft/join/restoration failure,
missing/foreign/mutated ACK or unverified early failure still veto clean shutdown
with exit 78. Ordinary legacy/generic monitor exit 78 remains a safety veto.
No unsupported --filter-mark or blockcheck embedded/stream/progress/deadline
flags are used. Background noninterrupting search and generic apply migration
remain deferred, as does immutable snapshot rotation for repeated runs.