Fprime Ground Input Tracing

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

The security agent flags asserts, overflow paths, and validation gaps reachable by ground input (commands, parameters, uplink, telemetry filters, file uplink). To do so, it must trace each predicate in an assert or arithmetic operation back to its source class:

• programmer-constant — compile-time constant, no input reachability.
• internal-state — derived from internal component state, not ground-reachable (modulo prior ground influence on that state, see §4).
• ground-input — derived from a ground command argument, parameter, uplink data, or any other value the ground operator controls.
• hardware-input — derived from a driver input or hardware register. Tracing for this class lives in fprime-hardware-input-tracing.

This skill is the trace procedure for the ground-input class.

1. Ground-input entry points

The following F Prime constructs receive ground input directly:

Each handler parameter at one of these entry points is ground- input at the moment it enters the agent's component. The trace proceeds forward from there.

2. Forward trace within a component

For an offending line L in component C (e.g., FW_ASSERT(x < LIMIT)):

1. Identify the variable x being asserted on.
2. Walk backward from L within C's method body using simple intra-procedural data-flow:
   • Direct assignment: x = y; → trace y.
   • Function-call result: x = foo(a, b); → if foo is in C, recurse; if foo is in Fw/Os/Drv, consult the source- class rules in §3.
   • Arithmetic combination: x = a + b; → trace both a and b; x is ground-input if either is.
   • Member access: x = this->m_foo; → mark m_foo as internal-state for this trace; cross-reference any code path that writes this->m_foo from a ground-input source class (§4).
3. If the variable is a handler argument at an entry point in §1, classify as ground-input and stop.
4. If the variable is a literal or a constexpr value, classify as programmer-constant and stop.

3. Library and primitive source classes

When in doubt, the agent classifies as the more dangerous class (ground-input if there is any plausible ground-reachable path) and appends a maintainer ping per maintainer-lookup.

4. Cross-procedural and cross-component flow

When the data crosses component boundaries (via an output port to another component's input port), the trace must follow the wiring in the topology:

1. From the offending line, identify the variable's origin within the local component.
2. If the origin is an input port handler argument, look up the port in the topology files (topology.fpp / instances.fpp / *Topology.cpp) to find the source component and port.
3. Recurse on the source component's output port: what value does it pass? Apply §2 within that component.
4. Continue until reaching a §1 entry point (→ ground-input), a §3 primitive (→ classify), or a hardware-input port (→ hand off to fprime-hardware-input-tracing).

The topology files relevant to the trace live in:

• Ref/Top/topology.fpp — the F Prime reference deployment's topology declaration.
• Ref/Top/RefTopology.cpp — the reference topology's generated C++ wiring.
• Ref/Top/instances.fpp — instance declarations for the reference deployment.
• Svc/Subtopologies/*/topology.fpp and Svc/Subtopologies/*/instances.fpp — subtopologies that are composed into deployment topologies.
• Svc/<Component>/<Component>.fpp (for component-internal port declarations).

Other deployments (mission-specific) use the same file naming inside their own <Deployment>/Top/ directory.

ByteStream driver disambiguation. When the trace reaches a port wired to a Drv::ByteStreamDriverModel-derived component, the agent must read the topology to determine whether that driver is the uplink-side (ground) or a hardware-side (radio, serial, network) byte stream. Same code, different upstream — the trace continues in this skill or hands off to fprime-hardware-input-tracing accordingly. If the topology is ambiguous (e.g., the same ByteStream driver is shared between ground and hardware paths), the agent classifies as ground-input (the more dangerous class) and adds a maintainer ping.

5. Worked example — ground-reachable assert

// In Svc/CmdDispatcher/CmdDispatcher.cpp (illustrative)
void CmdDispatcher::Dispatch_cmdHandler(
    FwOpcodeType opCode,
    U32 cmdSeq,
    U32 dispatchOpCode  // ← command argument
) {
    FW_ASSERT(dispatchOpCode < this->m_dispatchMax);   // L
    // ...
}

Trace from line L:

1. Variable dispatchOpCode.
2. Backward in the function body: no reassignment; the parameter is the source.
3. The parameter is a command-handler argument → §1 → ground-input.

The predicate operand dispatchOpCode is ground-input. Therefore FW_ASSERT on it is a ground-reachable assert → security-review.agent.md category 1 → **must fix**.

Suggestion: replace the assert with a validation:

if (dispatchOpCode >= this->m_dispatchMax) {
    this->log_WARNING_HI_InvalidOpcode(dispatchOpCode);
    this->cmdResponse_out(opCode, cmdSeq, Fw::CmdResponse::VALIDATION_ERROR);
    return;
}

6. Worked example — value derived from internal state but

ground-influenced

this->m_dispatchMax = newMax;   // newMax came from CMD_SET_MAX
// ...
FW_ASSERT(dispatchOpCode < this->m_dispatchMax);

Tracing m_dispatchMax:

1. m_dispatchMax is internal-state.
2. Cross-reference: is there a write path to m_dispatchMax from a ground-input source class?
3. CMD_SET_MAX_cmdHandler(newMax) writes it → newMax is ground-input.
4. Therefore m_dispatchMax is effectively ground-input (with sticky propagation: once an internal-state variable is written from a ground source, treat it as ground-input for the duration of subsequent traces).

The assert is still a ground-reachable assert via a one-step indirection. **must fix**.

7. Confidence calibration

The agent reports high confidence when:

• The trace reaches a §1 entry point within at most 3 hops, OR
• The trace is constrained to one component and reaches a §3 primitive cleanly.

The agent reports low confidence when:

• The trace crosses ≥ 4 component boundaries.
• The trace involves dynamic dispatch (function pointers, virtual calls into a base class with multiple subclasses).
• The agent cannot resolve a topology wiring (the relevant topology.fpp / instances.fpp / *Topology.cpp is not in the agent's read scope, or the wiring is conditional on a build option).

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

8. One-line summary

Walk backwards from the offending variable; classify origin as programmer-constant / internal-state / ground-input / hardware-input. Cross-component flow follows topology wiring. When in doubt, the more dangerous class wins and the maintainer is pinged.