Evidence-first AAA diagnostics for your own lab.

SECTION 1Install

Python 3.10 or newer. Nothing else is required — no cluster, no container, no second service.

python3 -m venv .venv && source .venv/bin/activate
pip install testpulse

What it runs on

The wheel is py3-none-any — pure Python, no compiled extension. The API, the viewer, the diagnosis engine and the CLI run anywhere Python 3.10+ runs. What differs between operating systems is not TestPulse; it is the external tools TestPulse shells out to, and every one of them is optional.

The recommendation, plainly: Ubuntu 22.04 LTS. That is what this build is developed and regression-tested on, it is the one platform where every optional tool installs with a single apt line, and it is the only one where testpulse-capture-setup --grant can finish the job for you. macOS is a close second. On Windows, prefer WSL2 with Ubuntu over native Python — not because the package fails natively, but because the AAA tooling around it assumes a POSIX box and you will spend your time on that rather than on your network.

The API holds about 96 MB resident, and 2 GB of RAM with any modern CPU is comfortable.

Optional extras

None are needed to start, and each one is a feature that degrades cleanly when absent rather than a hidden requirement.

SECTION 2First run

TestPulse refuses to start without a credential. That is deliberate: an unauthenticated API bound to 0.0.0.0 is a mistake you get to make exactly once.

Why there is a token, and who issues it

You generate it. Nobody issues it to you. There is no licence server, no account, and no activation call — TestPulse Pro runs entirely on your machine, and a vendor-issued key would mean phoning home, which this build never does.

The token exists for one specific reason: testpulse-api serves the viewer and the API from a single process on a single origin. There is no reverse proxy in front to add a credential, and baking one into a public download would be handing the key to everyone who downloads it.

export TESTPULSE_API_TOKEN="$(python3 -c 'import secrets;print(secrets.token_urlsafe(32))')"
testpulse-api

Any value works — the command above simply generates a strong one. Keep it. You need the same string again in the next step, and again on any other browser you open the viewer from. Then open http://127.0.0.1:8000; the viewer is served by the same process, so there is no second container to run and no separate front-end port.

Connect to TestPulseclick to enlarge

• The token is checked against /v1/health before it is stored, so a typo is rejected on the spot. Storing first and discovering the mistake later means every panel fails separately with no explanation.
• Once accepted it is saved in that browser's localStorage for that origin, and you are not asked again there. It is never written into the downloaded package and never leaves your machine.
• A different browser, a private window, or a different host:port is a different origin — you will be asked again. Enter the same token; it is not a new one.

TestPulse writes testpulse.db (SQLite) into the working directory on first start. Run it from a directory you intend to keep, or set TESTPULSE_DB_URL to a Postgres URL.

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/healthz   # 200
curl -s -H "Authorization: Bearer $TESTPULSE_API_TOKEN" \
     http://127.0.0.1:8000/v1/runs                                       # your runs

/healthz is unauthenticated on purpose so a load balancer can probe it. Everything under /v1/ requires the bearer token.

TestPulse Explorer — every panel this build shipsclick to enlarge

SECTION 3Diagnose a log you already have

First — how a classification is reached

Before you read your first verdict, it is worth seeing the model that produces it, because the output is deliberately not a single answer. TestPulse ships that model as a panel rather than leaving it to the documentation: Explorer → REFERENCE → Forensic Analysis Primer.

Forensic Analysis Primer — the nine-hop AAA pathclick to enlarge

Read the table left to right and the classification stops being a verdict handed down and becomes an address. A directory_path_degradation is hop 3 — RADIUS Server → LDAP/AD over LDAP, budget 500 ms. A dhcp_path_degradation is hop 5, Endpoint → DHCP Server on UDP/67-68, budget 4 s. transport_degradation on TCP/49 is hop 9, the TACACS+ leg. The cause family names the hop, and the hop names what to go and look at.

Three things follow from that table, and they are why a diagnosis here refuses to collapse into one word:

• A pass is all nine hops succeeding at once. Any one of them failing presents as "authentication failed", including the six that are not authentication. That is the whole reason "RADIUS is flaky" is never an acceptable answer — RADIUS is one hop of nine, and it is frequently the healthy one.
• Each hop is measured against its own budget, not a global timeout.
• The vocabulary is closed. The thirteen names below are the only classifications a diagnosis can return. It names one of them or it returns null — it never invents a label, so the same failure carries the same name across every run, every panel, and every export.

Diagnosing the log

The fastest path to value needs no configuration and no server at all. If you have a tac_plus.log or a radiusd -X capture, diagnose it directly:

testpulse-diagnose diagnose --protocol tacacs --file /var/log/tac_plus/tac_plus.log

{
  "decision": "reject",
  "confidence": 0.85,
  "events_parsed": 1,
  "evidence": { "TACACS_AUTHEN_REPLY_FAIL": 1 },
  "cause_family": "auth_semantic_failure"
}

--protocol accepts tacacs, radius, dot1x, eap_tls, peap, mab and coa. The 802.1X variants all ride the same RADIUS Access-Request/Accept/Reject exchange, so they share a parser; tacacs and coa have their own decision logic.

{
  "error": "no_events_parsed",
  "message": "No recognizable AAA log lines found for this protocol.
              Paste the raw tac_plus.log or radiusd -X output, not a summary or excerpt."
}

TACACS+ Auditclick to enlarge

SECTION 4Point it at your testbed

TestPulse ships with a sample testbed and loads it when you have not configured anything, so the Topology panel draws a network on first run instead of an empty box.

Every address in it is from the RFC 5737 documentation range, so every device reads as unreachable — that is the truthful result, not a failure, and it shows you the shape of the map before you own one.

Topology — first run, before any configurationclick to enlarge

export TESTPULSE_CONFIG=/path/to/my-testbed.yaml    # explicit, wins over everything
# ── or just save it as ./testbed.yaml where you run testpulse-api

Resolution order, first hit wins: TESTPULSE_CONFIG → ./testbed.yaml → ./env1.yaml → the packaged sample. The file drives everything: which devices exist, where their logs are, and where to capture. It is the source of truth — TestPulse has no hidden device list.

Credentials: named, never guessed

Prefer *_env and keep the secret out of the file:

radius:
  ip: 198.51.100.10
  secret_env: TESTPULSE_RADIUS_SECRET   # export TESTPULSE_RADIUS_SECRET=…

A literal value in the file works too. Then the file holds a secret: chmod 600 it and never commit it.

Declare only what you have

Sections you leave out are skipped, not assumed. If you do not declare a DHCP pool, TestPulse does not check lease placement and does not guess a range your network never agreed to — the result is "unknown", never "wrong". The same is true of ldap:, pcap: and switch:.

SECTION 5Reading a diagnosis

The three evidence planes

A verdict is only trustworthy when all three agree, so all three are always evaluated.

Verdict Summary — one run, all three planesclick to enlarge

The effective AAA path

Identity and policy lookups make DHCP, DNS and the directory part of the authentication path, not adjacent to it:

endpoint → DHCP/DNS → NAS/switch → RADIUS/TACACS+ → policy → LDAP/AD → enforcement

Read combinations, not single counters

The pattern across counter groups is the diagnosis. A few that are routinely misread:

Root Cause Trace — the same run as a causal chainclick to enlarge

SECTION 6Packet capture

Capture points are declared in your testbed YAML, so TestPulse captures what you tell it to and nothing else.

pcap:
  capture_points:
    - name: radius-wire
      bpf: "udp port 1812 or udp port 1813"
    - name: tacacs-wire
      bpf: "tcp port 49"

testpulse-pcap-start  <run-id> --duration 30    # run-id is positional
testpulse-pcap-status <run-id>
testpulse-pcap-stop   <run-id>

The run id is a directory name under the artifacts root (TESTPULSE_ARTIFACTS, ./artifacts by default) — the same root the API writes runs to, so a run created in the viewer is addressable from the CLI by its own name.

PCAP Analysis — six captures, 204 framesclick to enlarge

Bringing your own capture

Where TestPulse cannot capture for you — no SSH to the device, a span port you mirror by hand, a capture a colleague sent you — drop the file into the run directory under the device's name (radius.pcap, switch.pcap, dhcp.pcap, ad_ldap.pcap, wireless.pcap) and it is picked up as evidence.

SECTION 7AI narration is optional, and it is your key

TestPulse ships with no AI key and no AI subscription. Parsing, correlation, the deterministic diagnosis, the cause family and the evidence bundle all run locally with no network call. That is the product; AI is narration on top of it.

Install the provider SDK first — it is not in the base package, and which one you need depends on whose model you are using:

pip install 'testpulse[ai]'    # Anthropic or OpenAI, with your own key
pip install 'testpulse[aws]'   # Bedrock / SageMaker in your own AWS account

testpulse-diagnose configure --provider anthropic --api-key sk-ant-…
testpulse-diagnose status

status shows the active plan, entitlements, whether a BYOK key is configured, and — worth checking once — where that key actually landed. The CLI prefers your OS keychain and falls back to a 0600 file when no keychain backend is reachable, which on a headless box is the common case.

Environment / Settings — the AI/RAG groupclick to enlarge

Diagnosis Summary and the Copilot, side by sideclick to enlarge

How to tell a real similarity score from a fake one

With the [rag] extra, every run you keep is embedded and stored locally — that is what powers Analyzer (RAG), Similar Runs and cross-run comparison. A number between 0 and 1 always appears. What makes it worth anything is separation: the same failure described differently should score high, an unrelated failure low.

SECTION 8Driving TestPulse from an AI client (MCP)

With the [mcp] extra, TestPulse exposes its tools over MCP so an AI client can run tests, pull evidence, and read diagnoses directly.

pip install 'testpulse[mcp]'
testpulse-mcp        # stdio transport
testpulse-mcp-sse    # SSE transport

Point your MCP client at the command. testpulse-menu lists the available tools grouped by category.

MCP Tools, in the viewerclick to enlarge

SECTION 9The CLI

The package installs 31 commands. The ones worth knowing first:

Every command supports --help.

Test Runnerclick to enlarge

SECTION 10What this build does not include

Deliberately, and stated rather than hidden.

• The Trainer — the curriculum, grading and human sign-off loop is a separate product.
• Virtual-lab surfaces — live attack generation and the cluster panels need a lab this download does not ship. They are absent, not disabled: a greyed-out panel advertising something it can never run is worse than no panel.
• Vendor plugins — vendor-specific appliance packs ship separately. The core is RADIUS and TACACS+, which is what this build does well.

SECTION 11Troubleshooting

SECTION 12Feedback

Beta feedback goes through the product.

testpulse-diagnose feedback

Or the Feedback tab in the viewer. Feedback never includes your raw logs or captures — it carries your message and the build identifier, nothing else.

If you are blocked and need a person rather than a form, mail support@bmi2.com. That address is a forwarder to the maintainer, so it is a best-effort beta channel and not a contracted SLA. Attach the output of:

testpulse-diagnose status

It prints the plan, the entitlements in force, and whether a BYOK key is configured — which is most of what a first reply would otherwise have to ask you for. Say what you ran alongside it.