Skip to content

MÓDULO TREX.Art

Cisco TRex stateful traffic generator — line-rate TCP/UDP/IPSec.

Function

DPDK-based stateful traffic generator (Cisco TRex). 30 Mpps/core, 40M concurrent flows. Fills the gap K6.Art / PW.Art / iperf3 don't cover: line-rate stateful protocol simulation against an NGFW DUT.

Identity

Element Value
Plane DATA
Internal code trex-pod
K8s namespace oobi-fabric
OOBI slot .220 (primary) / .221 (HA standby, Enterprise)
Network DPDK NIC (separate from OOBI)
Tier gate Team+ (free/indie blocked; enterprise unlocks mixed-enterprise + http3-quic-saturation + custom profiles)
HW prereq DPDK-capable NIC + hugepages 1G + dedicated cores (kernel ≥ 5.4)
Patent Claim #17 — offensive + advanced traffic family
ADR ADR-0085

Bundled profiles (10)

The library matches the Investor Deck pitch "10 bundled enterprise traffic profiles, no script writing required":

Profile Category MinTier Default pps/core Notes
tcp-syn-flood ddos team 100k Half-open SYN storm; stresses DUT SYN-cache
udp-flood ddos team 200k Stateless UDP datagram storm
http-stateful stateful team 50k TRex ASTF HTTP request/response sessions
ipsec-aggressive ipsec team 30k IPsec/IKE tunnel traffic
dns-amplification-defense-test defense-test team 80k Asymmetric DNS burst (lab only)
https-handshake-storm stateful team 40k TLS 1.2/1.3 handshakes (no bulk data)
sip-call-setup-storm stateful team 25k SIP INVITE → 100 → 200 → ACK transactions
http3-quic-saturation stateful enterprise 60k QUIC over UDP/443 + 0-RTT data
voip-rtp stateful team 50k G.711-like RTP voice (20ms intervals)
mixed-enterprise stateful enterprise 70k Weighted 50/20/10/10/5/5 day-in-the-life mix

Custom operator-uploaded .py profiles unlock at enterprise tier and pass through the sandbox scanner (see below).

Operator controls

/admin/trex-art is the canonical surface (per CLAUDE.md "Dashboard is the ONLY operator interface"):

Panel Action
Live status Phase / current scenario / configured rate / simulated banner — polls /status every 2s
Library 10 bundled scenarios dropdown + tier-aware enable/disable
Start / Stop Form: duration_s, pps_per_core, cores (each clamped by tier)
Recent runs (ground-truth) Last 50 completed runs with intended-packet count for SPAN.Art cross-verify — polls /runs/summaries every 5s
Upload custom profile Drag-drop .py dropzone → server-side sandbox scan → inline accept (green) or reject (red, per-line violations)

Tier policy

Tier Access Max cores Max duration Max pps/core Custom profiles
free ❌ upsell modal — — — —
indie ❌ upsell modal — — — —
team ✅ 4 30 min 10 Mpps ❌
enterprise ✅ 16 24 h 30 Mpps ✅

Enforcement: orchestrator.Start() rejects with Accepted=false + operator-readable error when tier is below scenario.MinTier; numeric knobs (duration / pps / cores) are clamped to min(Config caps, TierLimits).

Sandbox scanner (custom profiles)

pkg/trex-art/internal/sandbox/ runs a Go-side line-based heuristic scanner (NOT a full Python AST walker) when an operator uploads a .py profile. Rejects:

Category Patterns
shell-out subprocess, os.system, os.popen, os.exec*
network socket, urllib, requests, httpx, http.client
dynamic-code exec(, eval(, compile(, __import__(
FFI ctypes, cffi
env-writes os.environ[] (read via .get() is allowed)

Comment + triple-quoted-string stripping means docstring mentions don't trip rules ("""os.system is bad""" in a docstring is fine). Max profile size: 256 KiB.

Operator gets per-line violation list rendered under the dropzone:

L3: import subprocess — subprocess is forbidden — profiles cannot shell out
L7: subprocess. — subprocess.* is forbidden — profiles cannot shell out

SPAN.Art ground-truth cross-verification

Every completed scenario produces a structured runsummary.Summary:

{
  "scenario_name": "https-handshake-storm",
  "started_at": "2026-05-24T18:30:00Z",
  "ended_at":   "2026-05-24T18:30:30Z",
  "duration_seconds": 30.0,
  "cores": 4,
  "pps_per_core": 40000,
  "intended_packets": 4800000,
  "exit_phase": "idle",
  "stopped_by_timer": true,
  "stopped_by_operator": false,
  "tier": "team"
}

SPAN.Art correlator polls /api/trex-art/runs/summaries/latest for the intended count + SPAN's /stats?since&until for wire-observed counts; drift > 5% over the run window → "DUT fast-path bypass suspected" (a SPAN.Art Pillar 5 finding per ADR-0085).

Endpoints: - GET /runs/summaries — newest-first array of last 50 - GET /runs/summaries/latest — 200 + most-recent, or 404

HW preflight

scripts/airgap-trex-preflight.sh validates at install time:

✓ DPDK-compatible NIC (Intel X710/XL710/E810 / Mellanox CX-5/CX-6/CX-7)
✓ hugepages 1G allocated (≥ 4 × 1G)
✓ Dedicated CPU cores via isolcpus (≥ 4)
✓ NIC bound to DPDK driver (dpdk-devbind.py --status)
✓ Kernel ≥ 5.4
✓ Memory ≥ 16 GB total
✓ NIC PHY cabled to DUT-facing trunk port

Test plan rejects launch if any preflight fails; operator gets actionable error + remediation steps in the Dashboard.

Key telemetry

Metric Description
trex_art_phase_info{phase,simulated} Current orchestrator phase
trex_art_scenarios_started_total Cumulative starts
trex_art_scenarios_completed_total Natural-completion exits
trex_art_scenarios_stopped_total Operator-stop exits
trex_art_scenarios_errored_total Error exits
trex_art_active_scenarios Currently running (gauge, 0 or 1)
trex_art_estimated_packets_generated_total Live count = pps × cores × elapsed
trex_art_configured_pps_per_core Current run's pps cap
trex_art_configured_cores Current run's core count

Grafana dashboard: grafana/provisioning/dashboards/trex/trex-art-overview.json.

Marketing exposure

"Powered by Cisco TRex" badge appears in: - Dashboard footer + about page - Marketing site PURE/Test Plan pages - Investor Deck v2 (alongside HAR.Art + SPAN.Art as differentiators) - Customer Deck (Cisco-aligned messaging — important for Cisco-heavy customers) - Sales sheets

Pitch: "Single bench. Browser-realistic (PW.Art) + scriptable HTTP (K6.Art) + line-rate stateful (TRex via Cisco) + raw throughput (iperf3). All your engines. One operator workflow."

Deferred (post-MVP)

  • Custom profile PVC persistence (matches HAR-B2 pattern — needs CronJob quota scan first)
  • TREX → SPAN.Art push notification on run end (currently SPAN polls)
  • ngfw-cert-baseline.py bundled scenario (lands after first NGFW vendor certification engagement validates the exact ASTF profile)
  • Cloud Endpoint TRex peer mode (cross-region origination)
  • Profile marketplace (community contributions, QA-signed)