157 lines
9.2 KiB
Markdown
157 lines
9.2 KiB
Markdown
# 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:
|
||
|
||
```json
|
||
{
|
||
"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.
|