Skill: Trace a value back to determine if it is hardware-controlled

Counterpart to fprime-ground-input-tracing. The security agent uses this skill to determine whether a predicate, an arithmetic operand, or an arbitrary value originates from a hardware input — i.e., from data crossing a Drv driver interface, a hardware register, a bus read, or an interrupt context.

A **must fix** from this skill is severity-identical to the ground-input equivalent: an assert reachable by hardware input DoS-es the spacecraft when the hardware misbehaves, an overflow reachable by hardware input is a DDoS vector, and a missing validation on hardware input is an exploitable surface.

1. Hardware-input entry points

The following F Prime constructs receive hardware input directly:

Each handler parameter at one of these entry points is hardware-input at the moment it enters the agent's component.

2. Forward trace within a component

Same procedure as fprime-ground-input-tracing §2. The only difference is the classification result and the entry-point table in §1 above.

m_state written from a hardware-source class is sticky: it is treated as hardware-input for the remainder of the trace.

3. Library and primitive source classes

4. Cross-component flow

Same algorithm as the ground-input skill §4. The trace follows the topology wiring; the difference is that the chain of origin ends at a hardware-input entry point (§1) instead of a ground-input entry point.

A buffer that flows Drv::UartDriver::recv → Svc::Deframer → Svc::Hub → application component is hardware-input at every hop unless the data is overwritten with internal state along the way.

5. Combined ground + hardware reachability

Some predicates are reachable from BOTH ground input and hardware input — for example, a buffer that ground can uplink AND that hardware can also push. In that case:

• Classify the predicate as ground-input + hardware-input.
• For triage: this is at least the most dangerous of the two applicable severities. In practice, this is **must fix** for an assert and **must fix** for unbounded copy / overflow / missing validation.

The agent's category for the finding is the more specific one (e.g., category 4–6 — hardware variants — if the assert is in a driver layer that is primarily fed by hardware, even if a ground path also exists). When both apply equally, the agent picks one category and notes the dual reachability in the comment body.

6. Worked example — hardware-reachable assert

// In Drv/I2cDriver/I2cDriver.cpp (illustrative)
void I2cDriver::Recv_handler(NATIVE_INT_TYPE port, Fw::Buffer& buf) {
    FW_ASSERT(buf.getSize() <= MAX_PAYLOAD);   // L
    // ...
}

Trace from line L:

1. Variable: buf.getSize().
2. buf is the handler parameter at the Recv input port of an Drv::* component → hardware-input.
3. buf.getSize() is a property of a hardware-input buffer → hardware-input.

The assert is hardware-reachable → category 4 → **must fix**.

Suggestion: replace with a validation that returns the buffer to the sender with an error code per the F Prime Fw::Buffer ownership contract:

if (buf.getSize() > MAX_PAYLOAD) {
    this->bufferReturn_out(0, buf);
    this->log_WARNING_HI_OversizedFrame(buf.getSize());
    return;
}

7. Worked example — hardware register read without bounds check

this->m_dma_len = REG_DMA_LEN;   // memory-mapped register read
// ...
memcpy(this->m_payload, src, this->m_dma_len);  // overflow vector

Tracing m_dma_len:

1. m_dma_len is internal-state, written from REG_DMA_LEN.
2. REG_DMA_LEN is a volatile register read → hardware-input.
3. m_dma_len is sticky hardware-input.

The memcpy length parameter is hardware-input. Without a bound check against sizeof(m_payload), this is a hardware-driven overflow → category 5 → **must fix**.

Suggestion adds the bound check (the exact form depends on the desired error response — drop, log, return-to-sender).

8. Confidence calibration

The agent reports high confidence when:

• The trace reaches a §1 entry point within 3 hops.
• The driver is well-known F Prime stock (I2cDriver, SpiDriver, UartDriver, etc.).

The agent reports low confidence when:

• The driver is custom and the agent cannot fully read its interfaces.
• The hardware boundary involves callback-based dispatch that the agent cannot resolve.
• The autocoded portion of the component is large and the agent cannot fully follow generated dispatch.

Low confidence → tag at the right severity + maintainer ping per maintainer-lookup.

9. One-line summary

Walk backwards from the offending variable; if origin is a Drv::* port, a hardware register, a /dev/ read, or an interrupt context, classify as hardware-input. Combined ground+hardware reachability inherits the more dangerous severity. Low confidence pings the maintainer; severity drives the tag.