Requirements specification¶

Version 0.2 · 6 September 2026.

Complete reference document, with diagrams and context: https://claude.ai/code/artifact/b2dd5c80-c37c-4a49-8f85-0e6702a5aeba

The identifiers below are stable and are cited in the source code's docstrings. grep -rn 'EF-05' src/ finds every implementation of a given requirement.

Collection and versioning¶

EF-01 — The platform backs up the configuration of network devices from several manufacturers.
EF-02 — It backs up designated sets of folders and files on Linux servers.
EF-03 — Each platform has two transports: an HTTPS API and an SSH/CLI access. The transport is adjustable per device: auto, api or ssh.
EF-04 — In auto mode, any switch to the fallback transport is logged and appears in the run report. A persistent switch is flagged as an anomaly, not as normal operation.
EF-05 — An artifact carries the transport that produced it. Two artifacts from different transports are never compared: a change of transport opens a new history lineage, explicitly flagged in the interface.
EF-06 — Two classes of artifact coexist: text (comparable line by line) and blob (deduplicated, not comparable).
EF-06 bis — TLS posture per device: chain verified, certificate pinned (declared SHA-256 fingerprint, loaded as the session's sole authority) or verification disabled. A device in factory configuration presents a self-signed certificate: pinning gives a real check without demanding an overhaul of its PKI. A disabled verification is flagged in the interface.
EF-07 — Each platform defines its normalisation rules, which exclude volatile lines and blocks (timestamps, counters, checksums, secrets re-encrypted on every read) from the fingerprint computation and from the comparison. The text kept stays raw and complete: restoring needs everything normalisation excludes.
EF-08 — Change detection rests on the fingerprint of the normalised artifact. A run with no change creates no version, but does record a successful run.
EF-09 — Line-by-line comparison between two versions of a text artifact, in the interface and through the API.
EF-10 — Backup triggerable on demand from the interface, the API and the command line, on a device, a group or a whole customer.
EF-11 — Backup schedulable per customer and per device (see DEC-01).

Inventory¶

EF-12 — Import from NetBox.
EF-13 — Import from a CSV file.
EF-14 — Creation and update through the REST API, so that imports can be scripted.
EF-15 — The same operations through the command line and through the web interface.
EF-16 — Strictly declarative inventory: no automatic discovery.
EF-17 — A device belongs to exactly one customer, and names the agent or agents of that customer authorised to reach it.

Multi-customer and agents¶

EF-18 — Isolation by customer of all data: inventory, configurations, logs, reports.
EF-19 — An agent is attached to a single customer; a customer may have several agents.
EF-20 — Enrolment by single-use token, resulting in an mTLS certificate scoped to the customer and revocable individually.
EF-21 — The agent establishes an outbound connection to the platform. No inbound flow towards the isolated network is required.
EF-22 — The agent is delivered as a container.
EF-23 — The agent carries on with its backups when the platform is unreachable, and replays its metadata on reconnection.
EF-24 — Device access credentials are delivered to the agent at execution time and are never written to its disk.

Storage and retention¶

EF-25 — One deduplicated repository per customer. No deduplication across customers.
EF-26 — Retention cascading over three levels: global → customer → device. The most specific value that is set wins.
EF-27 — A rule is expressed as a duration (days, months) and/or a number of versions kept per device.
EF-28 — Retention of the backups of a device removed from the inventory: a global setting, 1 year by default, with forced deletion possible and audited.
EF-29 — Agents hold append-only permissions on the storage. The purge runs from the central platform under a distinct identity, never present on an agent.
EF-30 — Object lock (Governance mode) over a configurable floor duration, independent of business retentions.

Restoring and exports¶

EF-31 — Restoring consists of making the file available. No push to the device. One explicit exception, added later and off by default: a Junos native configuration can be applied back to its device (beta), and only where an operator has enabled it at platform, customer and device level. The rule remains the default for every platform, every artifact and every device — see Restoring.
EF-32 — Navigation inside a Linux snapshot and download of a file or a subtree (see DEC-05). Comparisons are computed server-side; a file's preview and its comparison each have their own size limit (2 MiB and 5 MiB by default), and the difference rendered is capped (5,000 lines) with a pointer to downloading both versions.
EF-33 — Export of the whole of a customer's configurations in an open format.
EF-34 — Export of the database and the encryption keys, under a dual-control procedure and fully audited.
EF-35 — Optional Git export of text artifacts, for readability outside the platform.
EF-36 — Periodic and automatic verification that a sample of snapshots is restorable, with a trace usable in an audit.

Authentication and audit¶

EF-37 — Local accounts, each restricted to a given customer.
EF-38 — SAML 2.0 SSO at platform level (ADFS and Entra ID) for the provider's staff. No per-customer federation.
EF-39 — Roles: platform_admin, platform_operator, tenant_admin, tenant_operator, tenant_readonly, plus the holding role platform_pending assigned by SSO to an account recognised by the directory but attached to no known group (no permission, not assignable by hand).
EF-40 — The provider's staff have access to every customer. Any view or download of a configuration is logged with the user, the customer and the device concerned.
EF-41 — Append-only audit log, timestamped, exportable.

Reports and notifications¶

EF-42 — Daily report per customer, carrying the state of the fleet and not an account of the day's executions.
EF-43 — Consolidated daily report covering every customer, grouped by customer. The same structure as the per-customer report, so as to maintain a single template.
EF-44 — Two formats from a single source: formatted PDF for human reading, JSON for machine consumption.
EF-45 — Notifications by email and by webhook.
EF-46 — A collection failure constitutes a first-class category of the reports. It is never treated as an absence of change. The age of the last successful backup appears explicitly, device by device.
EF-49 — A device's state is computed from its expected cadence, never from the day's calendar alone. A device scheduled on Mondays and looked at on Thursday is compliant: the report shows its last successful backup and its age (“3 days ago”), it does not flag it as missing.
EF-50 — A report's default view is the exception. Out of 2,000 devices with 8 in trouble, the report presents the 8. The complete inventory stays available on explicit request, in the same structure.
EF-51 — An agent's attachment to its customer is immutable. Chosen at declaration — the customer being creatable in the same step — it never changes: reassigning a machine goes through revoking it, deleting the agent and declaring a new one. A device can only be authorised for the agents and credentials of its own customer; any other attachment is refused explicitly by the API, and job assignment never follows a link to another customer.
EF-52 — Capacity estimate. The platform measures each day what each customer really occupies in the object store, as well as the server's free space, and deduces a trend and an estimated saturation date, visible on the customer page and the dashboard. When a schedule is entered, it displays the volume projection at 1, 6 and 12 months (raw) and in steady state once retention is applied, as soon as two backups exist. Estimates are calibrated on the volume stored, never on transferred bytes alone, and a dense series of snapshots observed over less than a day feeds no projection.
EF-53 — Backup calendar. The Backups screen presents, month by month, each day's number of successful runs, the failures and the modifications detected; a day clicked lists its versions and its runs. Days are cut in the platform's display timezone (display_timezone setting), never in UTC.
EF-54 — Cross-cutting search. A single field, reachable from every screen, searches among customers, devices, agents and credentials — by name, hostname, address even partial, site, tag, short name or account. Results appear as you type and carry the backup state, the age of the last success and the customer concerned: the question “where does this device stand?” is settled without opening a page. Search tolerates typos, respects isolation strictly, checks rights family by family, and never queries or returns a secret's value.
EF-55 — Magnitude of changes. The difference between two successive versions of one lineage is measured in lines added and removed, on the normalised text, and recorded at the moment the version is written. The platform draws from it a ranking of the largest transitions — per artifact and per device — and a calendar intensity reflecting the lines touched per day. Versions whose magnitude is not measured are flagged as such, never counted as zero. The choice of versions to compare is made either by list or by calendar, and reading a configuration offers line numbers, search and full copy.
EF-56 — One credential per access path. A device carries a default credential and, optionally, a credential of its own for each supported transport. Every attempt — including after a fallback (EF-04) — sets off with the account of the path it takes: a FortiGate reads its API with a token and its SSH with a password, and the fallback cannot succeed otherwise. The credentials offered stay those of the device's customer (EF-51); the export cites their names, never the secrets, and re-import re-attaches each path automatically.
EF-57 — Fingerprint trust, cascading. How to behave in front of an unknown fingerprint — an API's TLS certificate, an SSH host key — is adjustable global → customer → device, field by field, like retention (EF-26): manual approval (default), trust on first use, or always refuse. An unknown fingerprint is recorded and made approvable from the interface; any change to an already approved fingerprint goes back on hold whatever the posture, the old and the new being presented side by side. A refusal never triggers a fallback to the other transport, and every decision is logged. Explicitly pinning a certificate on a device takes precedence over the cascade.

Deferred extensions¶

EF-47 — Compliance-testing engine running over text artifacts, with per-customer baselines.
EF-48 — Analysis of configurations by AI, switchable on per customer and disabled by default (see DEC-06).

Open decisions¶

DEC-01 — Backup frequency — settled (v0.2) Per-device scheduling, completed by on-demand triggering from the interface, the API and the command line. The supposed contradiction with the daily report was not one: a daily report is a state of the fleet, readable independently of the execution calendar. Each device's cadence serves to compute its staleness tolerance (EF-49).
DEC-02 — Nature of the 2 TB of Linux data Configuration files or application data? The daily rate of variation follows from it, and with it the storage at one year — a factor of ten between the two hypotheses (§02).
DEC-03 — Number of Linux servers and their spread across customers Sizes each agent's working-copy disk, a hardware item that is far from negligible.
DEC-04 — Floor duration of the object lock 14 or 30 days. A trade-off between the protection window and the space tied up.
DEC-05 — Restoring a large Linux snapshot A browser download is unsuited beyond a few gigabytes. Mechanism to be defined: subtree selection, archive generated on demand, time-limited link.
DEC-06 — AI analysis: internal model or external service Contractual and ISO 27001 impact (A.5.14). To be settled before the architecture of the work package is frozen, not at the moment of developing it.
DEC-07 — Procedure for exporting the encryption keys Dual control, output medium, possible escrow. A direct requirement of A.8.24.
DEC-08 — Size of the team and deadline for the first milestone Calibrates the division into work packages of §14, today proposed with no date constraint.
DEC-09 — SSO protocol SAML 2.0 is retained. OIDC deserves consideration for Entra ID: markedly simpler to operate and to maintain, for an equivalent functional result.