fprime-ground-input-tracing

name	fprime-ground-input-tracing
description	Use when tracing a value in F Prime code back to determine whether it originates from ground input (commands, parameters, uplink, telemetry filters, file uplink, or any uplink-stack component).

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:

Entry point	Where the data enters
Command arguments	Component::CMD_<NAME>_cmdHandler(...) parameters declared in the .fpp command definition.
Parameters	Component::paramSet_<NAME>(...) and Component::paramGet_<NAME>(...) flows; values originate from the parameter database, written from ground.
Uplinked file content	Svc::FileUplink-derived input ports / handler bodies.
Telemetry filter / packet selection	Svc::TlmPacketizer, Svc::ComLogger configurations that ground can influence.
Cmd opcodes / sequencing	Svc::CmdDispatcher dispatch path; opcode is ground-controlled, dispatch args inherit.
Async input ports labeled "from ground" in the topology	Any async input port wired in the topology from a ground-facing component (CmdDispatcher, ComQueue, FileUplink, etc.).
Deframer / framing layer	Svc::Deframer and any *Deframer-suffix component; the deframed buffer originates from the uplink byte stream and is ground-controlled.
Router	Svc::Router, Svc::FprimeRouter, and other router components that route uplink frames to handlers; routed payload inherits ground-input class.
Accumulator components	Uplink accumulators that gather partial frames before forwarding; their accumulated buffer is ground-input.
Detector components	Svc::CmdSequencer and similar detectors that scan an uplink buffer for sentinels / patterns; detected payload is ground-input.
ByteStream drivers (conditionally)	Drv::ByteStreamDriverModel-derived components carry ground-origin OR hardware-origin data depending on the topology wiring. The agent MUST consult the topology before deciding which tracing skill applies; see §4.

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

Construct	Source class
Literal, constexpr, enum value, static const	programmer-constant
Fw::Time::getTimeBase(), Os::IntervalTimer, similar	internal-state
Os::File::read() results (when reading a path that ground supplied)	ground-input (file content is ground-uplinked)
Component port input parameters at the entry points in §1	ground-input
Random / unpredictable internal state	internal-state
Fw::Buffer payload received over an external port	depends on the port's wiring; consult the topology

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.