technical-documentation.md

Technical documentation

This document is the index of the technical documentation of hodeishield that Article 13 of the Cyber Resilience Act, Regulation (EU) 2024/2847, asks the manufacturer to draw up, as set out in Annex VII. It follows the eight items of Annex VII in order. For each item it points to the file in this repository that holds the information, and says plainly what does not apply or is not available yet. Every statement about the product names the file that backs it, so that a reader can check it.

The manufacturer is Hodeitek S.L., Markole 17, 20550 Aretxabaleta, Gipuzkoa, Spain (NOTICE, user-information.md). The product is HodeiShield CLI; its command is hodeishield.

Each release keeps the copy of this document that applies to it, in that release's tag: https://github.com/Hodeitek/hodeishield-cli/blob/v<version>/docs/technical-documentation.md.

Classification and conformity route

• Product. hodeishield is a product with digital elements (Article 3(1)): software that is placed on the market and that connects to a remote data processing solution, the HodeiShield service (user-information.md).
• Category. It is in the default category. Under Article 7(1), a product is important only if its core functionality is one of those listed in Annex III (class I or class II), and critical only if it is one of those in Annex IV. The core functionality of hodeishield is to read one organisation's data from the HodeiShield API, from a terminal or a script (risk-assessment.md). It is a read-only API client: it is not, for example, a password manager, a VPN, a SIEM or an identity management system, and no other entry of Annex III or Annex IV describes it. The technical descriptions of those categories are in Commission Implementing Regulation (EU) 2025/2392.
• Conformity assessment. For a product in the default category, the manufacturer uses the internal control procedure, module A (Article 32(1)(a); Annex VIII, Part I). No notified body is involved. The manufacturer draws up this technical documentation, ensures that the design, development and vulnerability handling meet the requirements of Annex I, and draws up the EU declaration of conformity.
• Review of the category. The classification is checked again when the product changes substantially, or when the lists in Annex III and Annex IV or the implementing acts that describe them change (see Procedure).

Dates

• The obligations of Article 14 (reporting of actively exploited vulnerabilities and severe incidents) apply from 11 September 2026.
• The obligations of Article 13 and Annex I, the conformity assessment and the CE marking apply from 11 December 2027 (Article 71(2)).
• No declaration of conformity is signed and no CE marking is affixed before 11 December 2027. The template of the declaration is prepared now.

1. General description of the product

Annex VII, item 1	Where it is
(a) Intended purpose	user-information.md and risk-assessment.md: a read-only command-line client for the public /v1 API of HodeiShield
(b) Versions of the software that affect compliance with the essential requirements	Versions follow Semantic Versioning; each release is tagged v<version>, and the version is in Cargo.toml and printed by hodeishield --version (user-information.md). The notes of each release are in CHANGELOG.md. The risk assessment states the version it describes (risk-assessment.md)
(c) Photographs or illustrations of external features, marking and internal layout	Not applicable: the product is software only
(d) User information and instructions (Annex II)	user-information.md: manufacturer and contact, point of contact for vulnerabilities, intended purpose, secure use, support period, updates, decommissioning and the SBOM. The address of the declaration of conformity is in Product

Releases before 0.4.0 were published before the user information existed, and releases before the first one that contains this file were published before this documentation existed.

2. Design, development, production and vulnerability handling

(a) Design and development

• System architecture. hodeishield is a short-lived process on the user's machine, without a server part, daemon or plug-in interface (risk-assessment.md). The repository has two crates and a build tool (README.md): hodeishield-cli, the binary, and hodeishield-api, a Rust client for /v1 generated from the OpenAPI document vendored in openapi/v1.json; xtask is the generator and is not shipped. The CLI calls the client; the client builds the requests, authenticates, retries and limits the size of responses (CONTRIBUTING.md).
• Assets, interfaces and data. risk-assessment.md, the attack surface and data minimisation.
• Design decisions. docs/decisions and the decisions in risk-assessment.md. Decision record 0001 is a proposal: nothing in it is decided or implemented.
• Development rules. CONTRIBUTING.md: the Rust toolchain is pinned in rust-toolchain.toml, unsafe code is forbidden in the workspace (Cargo.toml, [workspace.lints.rust]), changes reach main only through pull requests with passing checks and signed commits (release-signing.md).
• Components. The dependencies are fixed in Cargo.lock, and the components of each release are listed in its SBOM (item 8). How they are chosen, monitored and fixed is in third-party-components.md (Article 13(5)). Drawings and schemes other than the above are not kept: the product has no hardware.

(b) Vulnerability handling

Element	Where it is
Software bill of materials	A CycloneDX SBOM for each archive, signed, and for the container image as an attestation (user-information.md)
Identification and monitoring of vulnerabilities and components	risk-assessment.md, point (1), and CONTRIBUTING.md
Vulnerabilities in third-party components	Assessment, fix and release rule, reporting to the component's maintainers with any fix, and the record of reports (third-party-components.md; Article 13(6))
Coordinated vulnerability disclosure policy	SECURITY.md
Point of contact for reports	Private reporting on GitHub and security@hodeitek.com; security.txt (.well-known/security.txt; SECURITY.md)
What happens after a report, fix targets and advisories	SECURITY.md, fix targets and advisories; the advisory template is security-advisory-template.md
Secure distribution of updates	Signed releases with checksums, Sigstore signatures and SLSA provenance (verifying-releases.md, release-signing.md); the update command of each channel is in user-information.md. The CLI does not update itself (risk-assessment.md)

Not yet available: the procedure for the reports of Article 14 to the CSIRT and ENISA, which is not documented in this repository yet. The APT and DNF repositories are not published yet; their signing key is described in release-signing.md.

(c) Production and monitoring

The product is built from a tagged commit by release.yml, which builds with --locked, signs, makes the SBOM and the provenance, and publishes a draft release. container-image.yml and package-managers.yml publish the container image and the Homebrew, Scoop, APT and DNF channels when a release is published. Who may change these, and how the pipeline is checked, is in release-signing.md and release-signing.md. The checks that run weekly after the release are listed under Test reports.

3. Cybersecurity risk assessment

risk-assessment.md is the assessment of Article 13(2) to (4): assets, threats T1 to T13 and their controls, how each requirement of Annex I, Part I and Part II is met or why it does not apply, the decisions behind them, and the residual risks. It is reviewed as described in Review.

4. Support period

The information used to determine the support period (Article 13(8)) is this section and SECURITY.md, which is the commitment made to users.

• Period. From 1.0.0, each major version receives security fixes for five years, counted from the release of its first version. Until 1.0.0 is released, the 0.x series has no end-of-support date and security fixes go into the latest 0.x release. The end date of version 1 is set when 1.0.0 is released and is then published in SECURITY.md and in the release notes.
• Rationale.
  • Expected time in use. hodeishield is a command-line client for a SaaS service that organisations use. It is installed on workstations, servers and CI runners (risk-assessment.md), where it can be part of scripts and pipelines that are expected to run for as long as the organisation uses the service.
  • Minimum. Article 13(8) requires a support period of at least five years, unless the product is expected to be used for less. Nothing in the intended purpose points to a shorter use.
  • Security fixes stay available while a version is supported, even after a HodeiShield subscription ends: every release is a public download, and installing or updating the CLI never requires a subscription (SECURITY.md).
• How end of support is announced. Twelve months before it ends, in SECURITY.md, in the security notice block of the README and in the release notes (SECURITY.md).

This rationale is open to review before 1.0.0 is released, because the support period starts then.

5. Standards, specifications and certification schemes applied

• Harmonised standards. No harmonised standard for the essential requirements of the Cyber Resilience Act is cited in the Official Journal of the European Union at the time of writing. None is applied. No common specification or European cybersecurity certification scheme is applied either.
• Solutions adopted. The requirements of Annex I, Part I and Part II are met by the measures in risk-assessment.md, point by point, with the reason when a point does not apply.
• Other specifications the project follows, as far as they can be seen in this repository:

Specification	Used for	Where
Semantic Versioning	Version numbers and the scripting surface	README.md, CHANGELOG.md
Keep a Changelog	The release notes	CHANGELOG.md
CycloneDX	The SBOM of each release	user-information.md
Sigstore signatures	Signing archives, packages, checksums, SBOMs and the container image	verifying-releases.md
SLSA provenance	Build provenance of the release archives	verifying-releases.md
RFC 9116 (security.txt)	Machine-readable contact for vulnerabilities	SECURITY.md
OpenAPI 3.1	The description of the /v1 API from which the client is generated	openapi/README.md
OpenPGP	The key of the APT and DNF repositories, once they are published	release-signing.md

6. Test reports

The reports of the tests are the runs of the workflows in .github/workflows on GitHub. Each release's CI runs, on its tag and on the commits before it, are its test reports. What each test checks, when it runs and where the result is are in CONTRIBUTING.md. The workflows are:

Workflow	What it does
ci.yml	Format, lint, code generation check, tests, cargo deny, cargo audit, the install script, the changelog and the commit messages, on every pull request and push to dev and main
security-tests.yml	CodeQL analysis of the Rust code and of the workflows, and OSV-Scanner on Cargo.lock, on every change and weekly
proxy-tls.yml	Behaviour behind a TLS-inspecting proxy, on changes to the CLI, the API client or Cargo.lock
workflow-lint.yml	actionlint and zizmor on the workflows, on every change under .github and weekly
scorecard.yml	OpenSSF Scorecard of the repository, on every push to main and weekly
openapi-sync.yml	Weekly check that the vendored OpenAPI document matches the one the API publishes
repo-builder-tests.yml	The APT and DNF repository builder refuses forged packages and indexes
release.yml	Builds, tests the MSI, signs and publishes a release, with its SBOM and provenance
container-image.yml	Builds, publishes and signs the container image when a release is published
package-managers.yml	Publishes the Homebrew, Scoop, APT and DNF channels when a release is published
release-integrity.yml	Weekly check that release runs, published files, signature log entries and image signatures match
repo-freshness.yml	Weekly check that the APT and DNF repositories are signed and current

Not available: a test report from a third party. The tests are the manufacturer's own.

7. EU declaration of conformity

The template follows Annex V. No declaration has been issued. From 11 December 2027, each release has its issued declaration in its tag, at https://github.com/Hodeitek/hodeishield-cli/blob/v<version>/docs/declaration-of-conformity.md.

8. Software bill of materials

Each release publishes a CycloneDX SBOM for each archive, and the container image carries one as a signed attestation (user-information.md). The SBOM is public, so it is available to a market surveillance authority without a request.

Procedure: declaration and CE marking

• Who signs. A legal representative of Hodeitek S.L. signs the EU declaration of conformity, for and on behalf of the manufacturer. The declaration is issued under the sole responsibility of the manufacturer.
• Before signing. The signatory checks that this documentation is up to date for the release, that the risk assessment has been reviewed for it, and that the CI runs of the release tag passed (item 6). Module A is internal control: the manufacturer decides on its own account that the product meets the requirements of Annex I.
• When the declaration is reviewed. It is reviewed and issued again for each release, and whenever the product is substantially modified (Article 3(30)), even between releases. The technical documentation is updated with each release.
• The declaration of a release is the file docs/declaration-of-conformity.md in that release's tag, with the fields of the template filled in. A simplified declaration (Annex VI) may be used and then points to the same address.
• CE marking. The product is software with no physical form or packaging, so the CE marking is shown digitally (Article 30(1)): on the EU declaration of conformity, and in the README and the release notes of the release it applies to. The marking follows the general principles of Article 30 of Regulation (EC) No 765/2008. Nothing is marked before 11 December 2027.
• Records. The version, place and date of issue, and the name and function of the signatory are written in the declaration.

Retention

The technical documentation and the declaration of each release are kept for at least ten years after the product is placed on the market, or for the support period, whichever is longer (Article 13(13)). The support period is in item 4.

The method:

• the copy of the repository in each release's tag on GitHub, which holds this documentation and the declaration as they were for that release, and the release's assets (archives, packages, SBOMs, signatures, provenance and SHA256SUMS);
• an archive of each release, with its source and documentation, kept by the manufacturer.