Governance and Infrastructure Control
=====================================

The cryptographic signing process described in this documentation ensures
that distributed release artifacts can be verified for integrity and
authenticity. However, cryptographic mechanisms alone are not sufficient
to guarantee trust.

The Shyft release model establishes a verifiable trust chain from
maintainer identity to installed software. This chain is described in:

:doc:`release-process`, :doc:`signing-keys`, and :doc:`package-verification`

In practice, the overall trustworthiness of a system depends not only on
what is verified, but also on how the surrounding infrastructure is
designed, operated, and governed.

Security mechanisms themselves — including inspection tools, monitoring
systems, and protective controls — may introduce additional complexity,
resource usage, and operational risk if not carefully managed. In
environments with strict requirements for availability, performance, or
deterministic behavior, such effects must be explicitly considered.

Well-governed systems tend to exhibit both improved security and improved
operational characteristics. By minimizing unnecessary components and
clearly separating trust boundaries, it is possible to achieve both strong
security guarantees and predictable, high-performance behavior.

For environments operating critical infrastructure — such as energy
market systems or grid operation tools — the governance of the systems
that produce and consume software releases is therefore equally important.

Two domains must be considered:

* Governance of the **release infrastructure**
* Governance of the **target deployment infrastructure**

These domains correspond to different parts of the Shyft trust chain and
must be governed independently.


Release Governance Model
------------------------

The following diagram illustrates the relationship between the source
repository, the controlled build infrastructure, the trusted signing
authority, and the operational deployment environment.

.. mermaid::
   :align: center

   flowchart TD

       subgraph Source["Source Governance"]
           A["Git repository<br/>Signed commits and tags"]
       end

       subgraph Build["Controlled Build Infrastructure"]
           B["Controlled build environment<br/>Reproducible build"]
           C["Unsigned release artifacts"]
       end

       subgraph Signing["Trusted Release Authority"]
           D["Signing host<br/>Nitrokey hardware key"]
           E["Signed packages<br/>+ PROVENANCE.txt"]
       end

       subgraph Deployment["Operational Infrastructure"]
           F["Operators / deployment systems"]
           G["Production energy systems"]
       end

       A -->|"checkout + verify"| B
       B -->|"build artifacts"| C
       C -->|"verify + approve"| D
       D -->|"cryptographic signing"| E
       E -->|"verified installation"| F
       F -->|"deployment"| G



Release Infrastructure Governance
---------------------------------

The systems used to produce signed Shyft release artifacts must be
operated under strict governance and control.

The release process is designed to be executed entirely within a trusted
domain, where both build and signing operations are controlled and auditable.

Recommended practices include:

* Controlled build hosts operating under an approved build-host profile
* Use of minimal, version-controlled, and reproducible build images
* Verification of signed source tags before build
* Execution of builds in isolated environments (e.g., containers)
* Optional restriction of network access during the build step
* Hardware-backed private keys (e.g., Nitrokey or smartcards)
* Controlled physical and logical access to signing infrastructure
* Documented release procedures requiring operator authorization
* Auditable logs for build and signing operations
* Reproducible builds from signed source tags

The build environment should be treated as part of the trusted computing
base and must be provisioned, maintained, and audited accordingly.

Final release approval and promotion must remain governed and auditable.

In highly secured environments, the signing process may require the
presence of multiple operators ("two-person rule") before release
artifacts are approved.

The integrity of this environment directly affects the trustworthiness of
the signing process and the resulting release artifacts.

Key management and signing procedures are defined in:

:doc:`signing-keys` and :doc:`../security/identity/gpg-ssh-keys`


Target Infrastructure Governance
--------------------------------

The environments that deploy and execute Shyft should also be operated
under controlled governance.

Examples include:

* Physical security of servers and data rooms
* Controlled administrative access
* Separation of operational systems from general IT infrastructure
* Monitoring and audit logging of administrative actions
* Controlled update procedures for production systems
* Verification of software provenance and signatures before deployment

For operational technology (OT) environments, where Shyft may interact
with systems affecting power system stability, these governance controls
are essential.

Verification procedures for release artifacts are described in:

:doc:`package-verification`

Separation of Inspection and Trust
----------------------------------

Security inspection tools — such as vulnerability scanners, SBOM analyzers,
EDR systems, antivirus solutions, and network inspection devices — are
commonly used to improve visibility and detect potential risks.

However, these tools must not automatically be considered part of the
trusted computing base.

Many such tools:

* are complex and frequently updated
* may be closed-source or externally managed
* require elevated privileges
* may access or process large portions of the system state

If deployed directly within trusted environments, they can unintentionally
expand the trust boundary and introduce additional risk.

Principle
~~~~~~~~~

Security inspection and analysis should, where possible, be performed in a
**separate inspection domain**, distinct from the trusted release and
deployment environments.

In this model:

* The trusted domain is responsible for building, signing, verifying, and
  executing software
* The inspection domain is responsible for analyzing artifacts and producing
  reports

Artifacts may be exported from the trusted domain for inspection, but should
be **re-verified cryptographically** before being accepted back into a
trusted environment.

This separation preserves the integrity of the trust chain established by
the Shyft release process.

Application to Release Infrastructure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For release infrastructure, this means:

* Build and signing environments should remain minimal and controlled
* External tools such as SBOM generators or vulnerability scanners should not
  be required for producing release artifacts
* Inspection tools may analyze build outputs or images, but must not be able
  to modify or influence the release process

Application to Target Infrastructure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For deployment environments, this principle implies:

* Monitoring and inspection tools should be carefully governed and isolated
* Where possible, inspection should be performed using external systems or
  dedicated analysis environments
* Real-time or inline inspection tools (e.g., EDR, antivirus) should be
  evaluated with respect to their impact on system integrity and trust
  boundaries

Network-based inspection may be implemented using controlled observation
points, such as mirrored traffic (SPAN) ports or one-way (data diode) taps,
allowing analysis without introducing bidirectional influence on the
protected systems.

Balanced Use of Security Tools
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This principle does not discourage the use of security inspection tools.

Rather, it provides guidance on how to use them safely:

* treat inspection tools as **untrusted or semi-trusted components**
* avoid making them part of the trusted release or execution path unless
  explicitly governed
* ensure that cryptographic verification remains the final authority for
  accepting artifacts

By maintaining a clear separation between **inspection** and **trust**, it is
possible to benefit from advanced security analysis without weakening the
overall security model.


Operational Considerations
~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to trust-boundary considerations, security inspection tools may
also affect system stability and performance.

Examples of potential impacts include:

* Increased resource usage (CPU, memory, I/O), which may be significant in
  high-performance or latency-sensitive environments
* False positives leading to unintended quarantine or blocking of critical
  system components
* Behavioral changes following rule or signature updates
* Interference with normal system operation, particularly in tightly
  controlled or deterministic execution environments

For systems operating under strict availability or performance requirements,
these effects must be carefully evaluated.

In such environments, it is often preferable to:

* perform inspection in separate analysis domains
* avoid inline or real-time modification of system state
* treat inspection results as advisory rather than authoritative

This approach helps ensure that security mechanisms do not inadvertently
impact the reliability of the systems they are intended to protect.


Relationship to the Shyft Release Model
---------------------------------------

The Shyft release model described in this documentation provides a
transparent and verifiable software supply chain based on:

* Signed source revisions
* Controlled and reproducible build environments
* Hardware-backed cryptographic signing
* Verifiable release artifacts and provenance

Together, these elements establish a complete trust chain from
maintainer identity to installed software.

However, the ultimate trustworthiness of a deployment depends on how
organizations operate their infrastructure and governance processes.

Organizations deploying Shyft in critical infrastructure environments
are encouraged to integrate the described release process into their
own governance and security frameworks, including:

* Controlled build infrastructure operated within their trust domain
* Independent verification of release artifacts
* Auditable deployment and update procedures

Future versions of this documentation will provide guidance on how these
principles can be implemented in physical and network infrastructure,
including separation of administrative, release, control-plane, and
application environments, as well as dedicated inspection domains.

These infrastructure patterns are intended to reinforce the trust boundaries
described here.

See also:

* :doc:`release-process`
* :doc:`signing-keys`
* :doc:`package-verification`
* :doc:`../security/index`