Skip to main content

Blueprint

ci

One contract, two enforcers: Blueprint checks a QNX 8.0 system against its message architecture in CI, and turns the same file into a security policy the kernel enforces.

A QNX system is a set of processes that talk through synchronous messages. The design usually lives in someone's head or on a whiteboard: display asks nav, nav asks gps, nobody calls back up the chain, and a dead camera must not take the screen with it. Blueprint lets you write that design down in a few lines of YAML, the contract.

  • Before release it checks a real kernel trace against the contract. When the system does something the design does not allow, the build fails and the report says which process did what, with the trace events to prove it.
  • After release the same file becomes the channel rules of a QNX security policy. Booted in secure mode, the kernel refuses a connection the contract does not allow: cockpit: cannot open cockpit-gps: Operation not permitted.

System Profiler shows you a trace. Blueprint knows what the trace should look like and tells you where it does not.

One contract, checked in CI against the kernel trace and enforced by the kernel as a security policy

See it without installing anything: the reports for every recorded scenario and the codelab are at dmitriytopka.github.io/qnx-blueprint. A 2:53 video of all of it: youtu.be/rqJFxPH5Bjs.

For judges

Links point at release v0.3.0, so the lines stay where they are.

Criterion Where to look What it shows
Technological Implementation kev.py, ipc.py, checks.py, docs/TRACEPRINTER.md the trace format read from scratch and compared with QNX's traceprinter: 1,071,509 events in 25 traces, none missing or different; 137 tests
Design blueprint demo, the reports, action.yml one command with no target, an HTML report, JUnit XML and a GitHub Action for CI
Potential Impact demo/external/qpp, demo/external/socketcan two BlackBerry systems we did not write: a stopped server found, and eight weak spots in Blueprint fixed on their traces
Innovation & AI Creativity explain.py, review.py, mcp_server.py Claude explains and reviews but never judges; an event id it cites that the trace does not have is dropped
Codelab bonus the contract codelab, the secure-image codelab a secure QNX 8.0 image from a policy you can check, with a recorded live run
QNX-specific bonus demo/cockpit/secpol/evidence mkqnximage --secpol=secure on x86_64 and aarch64: serial logs, the compiled policy matching /proc/boot/secpol.bin, the kernel saying Operation not permitted

Try it in one minute

No QNX target, SDP or API key needed. The repository ships traces recorded on QNX 8.0 (x86_64, QEMU) from the demo system in demo/cockpit.

pip install qnx-blueprint
blueprint demo

The package is on PyPI and carries the recorded traces. From a clone:

python3 -m venv .venv && . .venv/bin/activate      # or any Python 3.10+ environment
python3 -m pip install .
blueprint demo

Without a clone, pip install git+https://github.com/DmitriyTopka/qnx-blueprint in the same environment installs the same recorded traces with the package, and blueprint demo runs from any directory. Use a virtual environment on Ubuntu 22.04: its system pip installs the package as an empty UNKNOWN without an error.

scenario              expected  got   checks                            story
ok                    pass      pass  -                                 The system as designed.
deadlock              fail      fail  unexpected-edge, wait-cycle       gps asks nav for a hint while nav is waiting on gps.
backdoor              fail      fail  unexpected-edge                   display reads gps directly, bypassing nav.
camera-hang           fail      fail  isolation                         The camera stops answering; display has no protection and freezes.
camera-hang-fixed     pass      pass  -                                 Same stuck camera, display reads it from its own thread.
...

Open out/deadlock.html for the report, or load out/deadlock.perfetto.json at ui.perfetto.dev to see every message as an arrow between threads.

A step-by-step tutorial in the QNX codelab format is in docs/codelab, and answers to the usual questions (overhead, false alarms, what Claude sees, what is not covered) are in docs/FAQ.md.

The contract

system: cockpit
processes: [gps, nav, camera, logger, display]
allow:                      # who may send messages to whom
  - display -> nav
  - display -> camera
  - display -> logger
  - nav -> gps
  - nav -> logger
reply_budget_ms:            # how long a server may keep a client waiting
  nav: 50
  default: 20
isolation:                  # when camera dies or hangs, display keeps working
  camera:
    must_survive: [display]
    min_progress: 3
priority_inversion_ms: 2    # experimental: time a waiting client may lose
                            # to lower priority work
cycle_ms:                   # real-time loops, from the client's side:
  display -> nav: 100       # display needs a route from nav at least every 100 ms

reply_budget_ms is the server's promise, cycle_ms the client's deadline: display draws a frame about every 55 ms and needs nav's answer for each one. The demo's realtime.yaml is blueprint.yaml plus that line.

To start from a system that already runs, record a trace and let Blueprint write the first draft:

blueprint init run.kev --system cockpit -o blueprint.yaml

It lists the application processes that message each other (QNX services such as procnto, devb-* and io-sock are left out, --only picks them by hand), every edge it saw with its message count, and reply budgets at four times the slowest reply in that trace. A draft taken from a trace with a backdoor contains the backdoor, so read it and delete what you did not design.

--review asks Claude to read the draft with you. For every edge it gets the message count, the first sends and what they carried, who else talks to the same server, and the source you pass with --source, and it marks the edges worth a question as comments in the draft. On the backdoor trace, with no source passed, it marked one edge of six:

allow:
  - display -> camera             # 50 messages
  # review (SUSPICIOUS): Display reads gps directly, bypassing nav, which already queries gps every cycle. Display sends the same 0x01 request as nav, a few tenths of a millisecond after nav's query; confirm this direct path was designed and is not a leftover shortcut. Events 57138, 57457, 58999, 57029, 57363, 58905.
  - display -> gps                # 50 messages
  - display -> logger             # 50 messages

That answer cost about 0.03 USD (2,075 input and 905 output tokens) and is cached in demo/cockpit/explanations, so blueprint init demo/cockpit/traces/backdoor.kev --system cockpit --review --offline --cache demo/cockpit/explanations prints it again without a key. It needs pip install 'qnx-blueprint[explain]'.

Nothing is removed. An edge Claude names that is not in the draft, and an event id it was not given, are dropped; a mark with no evidence left says unverified. Reviews are cached like explanations.

Checks

Check Fails when
unexpected-edge a process sends messages to a server the contract does not allow
wait-cycle threads end the trace waiting on each other in a loop (deadlock)
stuck-reply a server took a message and never replied
reply-budget a server replied, but slower than its budget
cycle-overrun a client went longer than its cycle_ms without an answer, or its loop stopped
kernel-denied the kernel refused a connection with EPERM: a security policy at work
isolation a process died or stopped answering and took a protected process down with it
no-traffic the trace shows no answered message at all, so it proves nothing
trace-loss kernel buffers are missing from the trace (a gap in the per-CPU buffer sequence), so no verdict on it can be trusted
priority-inversion a client waits on a lower priority server while threads with a priority in between use the CPU (experimental, on when the contract sets priority_inversion_ms)

A read() that waits in the server for data (a socket, a device, a pipe) is the client waiting for input, not the server's latency: when the thread that took it spent the wait parked (CONDVAR, SEM, back in MsgReceive), it counts neither against reply_budget_ms nor as a stuck reply. If the data must come in time, give the client a cycle_ms.

The HTML report for the hung camera: the broken edge in red, the finding first, the trace events behind it

Every finding lists the trace events it is based on. Exit code 0 means pass, 1 means the contract is violated, 2 means bad input.

Where the time went

A slow reply or a missed cycle comes with a breakdown of its worst case, read from the thread states in the trace. The parts add up to the whole:

FAIL  [reply-budget] logger answers display too slowly
      15 of 31 replies from logger to display took longer than 20 ms; worst 52.6 ms. ...
      where: worst 52.6 ms: server preempted 50.4 ms (mostly media at priority 20, 50.3 ms), server running 2.0 ms, ...
FAIL  [cycle-overrun] display -> nav cycle missed its period: worst gap 114 ms against 100 ms
      where: in the longest gap (113.8 ms) display spent: sleeping (NANOSLEEP) 55.3 ms,
      waiting on logger 48.5 ms (there: server preempted 46.6 ms (mostly media at priority 20, 45.1 ms)), ...

Queued behind another client, preempted (by which thread, at what priority, wall time), running, sleeping, or waiting on its own call to another server, followed one level into that server. The HTML report draws it as a bar.

Record on your target, with faults

If the target runs sshd, one command records and checks:

blueprint record root@192.168.1.20 -c blueprint.yaml --inject camera@1.5 -d 5 \
    -o run.kev --html report.html

This starts a wide trace on the running system, kills camera with SIGKILL 1.5 seconds in, saves pidin when the trace stops, copies run.kev and run.pidin back and checks them against the contract. Nothing is installed on the target: it only needs tracelogger, pidin, slay and sleep from a stock QNX 8.0 image. --inject takes any process from the contract and can be repeated; --inject qpp@1.5:stop freezes it with SIGSTOP instead of killing it, and continues it after pidin has seen it stopped. When two instances of one binary run, --inject 'io-sock[prefix=/can]@2:stop' picks the one whose command line contains prefix=/can and leaves the other alone. --start "..." launches the system inside the trace instead of attaching to one that is already up, and --ssh "..." replaces the ssh command (for a jump host or a VM in a container). A kill that finds no such process is reported, so a test that never broke anything cannot pass by accident.

Recorded on QNX 8.0 in QEMU against the demo system:

$ blueprint record root@localhost -c demo/cockpit/blueprint.yaml --inject camera@1.5 -d 4
inject camera: killed 1 process(es)
FAIL  [isolation] camera died and took display down with it
      camera died; display died 38 ms later.
FAIL: cockpit 1 error, 0 warnings

The same command against the fixed display passes.

Without ssh, record by hand and copy the files:

tracelogger -w -s 5 -f /tmp/run.kev      # -w: wide mode, see Limits
pidin > /tmp/run.pidin                   # thread states when the trace stopped
blueprint check run.kev --contract blueprint.yaml --html report.html --perfetto run.perfetto.json

--junit results.xml writes JUnit XML with one test per check, for GitLab, Jenkins or any other CI that reads test results.

The .pidin file next to the trace is picked up automatically. It matters when the system was already stuck before tracing started: blocked threads produce no events, and only pidin shows who waits on whom.

Let the kernel enforce it

The learned policy fails against the contract, and the kernel refuses the backdoor in secure mode

A trace shows what the system did. A QNX security policy decides what it may do. Blueprint writes the channel rules of a policy from the contract:

blueprint secpol -c blueprint.yaml --attach nav=/dev/name/local/cockpit-nav ... -o cockpit.secpol
type display_t;
allow_attach nav_t /dev/name/local/cockpit-nav;
# display -> nav
allow display_t nav_t:channel connect;

The output compiles with secpolcompile. It covers only the processes in the contract, so merge it into the policy for the whole system.

It also works the other way. secpolgenerate learns a policy by watching the system, and it learns whatever happened, a bad build included. Check what it learned before you ship it:

$ blueprint secpol -c blueprint.yaml --check learned.secpol
FAIL  [secpol] policy lets display connect to gps, which the contract forbids
      learned.secpol line 202 allows display_t to connect to gps_t. ...

blueprint check run.kev --secpol learned.secpol runs the same comparison next to the trace checks. On QNX 8.0 (x86_64 and aarch64) booted in fully secure mode with a policy that matches the contract, the backdoor build fails in the kernel: cockpit: cannot open cockpit-gps: Operation not permitted, and so does open() on the gps resource manager. How the demo policies were made is in demo/cockpit/secpol. A codelab walks through all of it from scratch: Lock a QNX 8.0 system to its design.

The refusal is in the trace too. A ConnectAttach the policy denies exits with ret_val:-1, errno:1, and a trace recorded on the secure image fails with

FAIL  [kernel-denied] the kernel refused display's connection to gps, which the contract forbids
      ConnectAttach from display to gps failed 140 time(s) with EPERM: the security policy
      blocked the path the contract leaves out. The build still tries it, ...

A refused edge that the contract allows means the policy and the contract disagree, or the process was started without its type. The secure-mode traces are in tests/data/secure/, and the serial logs and sessions of both secure images in demo/cockpit/secpol/evidence.

Explanations by Claude

export ANTHROPIC_API_KEY=...
blueprint check run.kev -c blueprint.yaml --explain --source src/display.c --html report.html

The checks decide what is wrong. Claude is only asked to explain one finding at a time: it gets the trace events behind it (each with an id), the contract and the source you pass, and returns the cause, the QNX call at fault and a patch. Event ids it did not receive are removed, and an explanation left with no real evidence is marked unverified. Answers are cached next to the contract, so the demo and CI runs work offline. One explanation costs about 0.06 USD with claude-opus-5-5.

For coding assistants (MCP)

python3 -m pip install "qnx-blueprint[mcp] @ git+https://github.com/DmitriyTopka/qnx-blueprint"
blueprint mcp

blueprint mcp is an MCP server on stdio with five tools: check_trace, draft_contract, write_policy, check_policy and list_demo_traces. Add it to your assistant's MCP configuration (command blueprint, argument mcp) and it can check a trace, read where the time went and propose a fix in one conversation. The tools read local files only; recording a trace over ssh stays a command you run yourself.

In CI

- uses: DmitriyTopka/qnx-blueprint@v0.3.0
  with:
    trace: traces/nightly.kev
    contract: blueprint.yaml

The action writes report.html, report.json, junit.xml (one test per check, for any CI test view) and a Perfetto trace to blueprint-report/, adds a summary to the job page and fails the job on any violation.

What it uses from QNX

File QNX feature Why
blueprint/kev.py kernel trace file format, instrumented kernel procnto-smp-instr reads tracelogger output on any host, no SDP needed
blueprint/ipc.py MsgSendv, MsgSendvnc, MsgReceivev, MsgReplyv, MsgError kernel calls; COMM SND_MESSAGE, REPLY_MESSAGE; ConnectAttach, ChannelCreate rebuilds every message transaction with client, server, channel and timing
blueprint/ipc.py resource manager protocol (_IO_CONNECT, _IO_READ, ...) open() and read() on a device are messages too, so edges to resource managers are checked the same way
blueprint/ipc.py thread states SEND, RECEIVE, REPLY knows who is blocked on whom when the trace ends
blueprint/checks.py thread state events with priority, _NTO_CHF_FIXED_PRIORITY from ChannelCreate priority inversion: who ran while a waiting client's server sat READY
blueprint/snapshot.py pidin blocked-on column sees waits that started before the trace
blueprint/secpol.py security policy language: type, allow_attach, channel connect, the channel_connect ability; secpolcompile, secpolgenerate, on -T turns the contract into kernel-enforced channel rules and checks a learned policy against it
blueprint/record.py tracelogger -w, slay -s KILL, pidin on the target over ssh kills a process while the trace runs, so its death and the reaction of its clients are both in the trace
blueprint/checks.py synchronous message passing semantics deadlock, stuck server, reply budget, isolation
demo/cockpit/cockpit.c name_attach, name_open, MsgSend, MsgReceive, MsgReply, pulses, _NTO_CHF_UNBLOCK, _NTO_CHF_FIXED_PRIORITY; gps as a resource manager (resmgr_attach, iofunc_*, dispatch_*) a five-process system with realistic faults

One thing the demo shows that surprises people: a TimerTimeout on MsgSend does not protect a client from a server that stopped answering. Channels created by name_attach() have _NTO_CHF_UNBLOCK set, so a REPLY-blocked client that times out stays blocked until the server handles the unblock pulse. The fixed display reads the camera from its own thread instead.

On a system we didn't write

demo/stock is a trace of a QNX image with none of our processes running, only QNX's own services. blueprint init --all drafts its map (the shell, the process manager, devb-eide, io-sock, pipe, io-usb-otg, eight message paths) and the check against that draft passes. See demo/stock/README.md.

demo/external/qpp is BlackBerry's open-source QNX POSIX Publish Subscribe service, built unchanged and traced healthy, with its server stopped and with its server killed. Blueprint names the stopped server and the client left REPLY-blocked on it, and the run found four weak spots in Blueprint itself, now fixed. See demo/external/qpp/README.md.

demo/external/socketcan is BlackBerry's SocketCAN for io-sock on a virtual CAN bus, with the CAN stack stopped and killed under its clients. Its blocking reads made Blueprint fail a healthy system; that and three more weak spots are fixed. The prebuilt module needed a small shim of ours to load, see demo/external/socketcan/README.md.

Is the parser right?

Every trace in the repository was also printed with QNX's own traceprinter on the target and compared with Blueprint's reading, event by event: 1,071,509 events on x86_64 and aarch64, with and without wide mode and in secure mode, and not one missing, extra or different. The table is in docs/TRACEPRINTER.md, and python -m blueprint.tpcompare run.kev run.tp does the same for your own trace.

Limits

  • Times come from the trace clock. Under QEMU emulation they are inflated, so budgets in the demo are generous. Measure absolute latencies on hardware.
  • A trace that lost kernel buffers fails with trace-loss instead of being checked as if it were complete. We detect the loss from gaps in the buffer sequence numbers; we could not make QEMU drop a buffer, so the check is tested on a real trace with one buffer cut out.
  • Size: a 2 MB trace (51,000 events) takes about 0.4 s and 70 MB of memory. The parser keeps the whole trace in memory, so memory grows with the trace; a trace of a few hundred megabytes would need several gigabytes (an estimate, not measured). Record a few seconds around the behaviour you check.
  • A read that was already waiting when the trace started shows only in pidin, without its message, so Blueprint cannot tell a reader waiting for data from a stuck server and reports it. Start the system inside the trace (record --start) when its clients block in read().
  • Two instances of one binary (two io-sock) are one process in a contract.
  • Record with tracelogger -w. Without wide mode the trace still shows who sent to whom and who was blocked (on the healthy demo it gave the same five edges), but thread priorities and message contents are missing. Blueprint then warns (trace-mode), and fails if the contract asks for the priority inversion check, rather than skip that check quietly.
  • The priority inversion check is experimental. A QNX server normally takes its client's priority while it handles the message, so the check does not look for "server priority lower than client". It looks at what the kernel actually scheduled: the server READY at a lower priority while threads between the two priorities run. On a normal channel that should not happen; it shows up with _NTO_CHF_FIXED_PRIORITY channels. It has no false alarms on the recorded demo traces, but it has not seen many real systems yet.

Building the demo system

demo/cockpit builds with qcc from QNX SDP 8.0 and runs in a QEMU image made with mkqnximage, on x86_64 or on aarch64 (--arch=aarch64le, which needs the com.qnx.qnx800.target.qemuvirt and com.qnx.qnx800.target.driver.virtio.startup packages). The same scenarios give the same results on both. On the virt board the block device has to come first on the QEMU command line, since virtio-mmio addresses follow the order of the devices:

qemu-system-aarch64 -machine virt-4.2 -cpu cortex-a57 -smp 2 -m 1G \
  -drive file=output/disk-qemu.vmdk,if=none,id=drv0 -device virtio-blk-device,drive=drv0 \
  -netdev user,id=net0,hostfwd=tcp::2223-:22 -device virtio-net-device,netdev=net0 \
  -kernel output/ifs.bin -display none -serial file:serial.log

demo/cockpit/cockpit-run.sh records one scenario on the target. No SDP files, headers or images are included in this repository.

How it was built

Dmytro Topka built Blueprint for the QNX Global Hackathon, starting on November 3, 2026, with Claude Code (Anthropic) as the coding agent. The idea was picked after two rounds of review against the judging criteria and the other entries. Every claim about QNX was checked on a running QNX 8.0 target before it went into the code or the docs, and several first guesses did not survive that: the pid in a send event, what a send timeout does on a name_attach channel, which errno a denied connection gets, why a learned policy had no rules. The commit history shows the work as it happened.

AI use

  • Building it. Claude Code (Anthropic) wrote most of the code and the docs as the coding agent, directed and reviewed by the author. Every claim about QNX was checked on a running QNX 8.0 target first, and the tests and recorded traces in this repository are the evidence.
  • Inside the tool. --explain and init --review call claude-opus-5-5, and the MCP server lets a coding assistant run the checks itself. The model explains and suggests; the checks alone decide pass or fail, and any event id it cites that the trace does not have is removed. Without an API key every check still runs.
  • The videos. The narration is an AI clone of the author's own voice, and the typing in the terminal recordings is replayed; the commands and their output are real runs on QNX 8.0 in QEMU.
  • The codelab checks. Its four test runs from an empty folder were made by AI agents, not people, and are reported as such in OUTSIDER_RUN.md.

License

Apache-2.0. QNX is a trademark of BlackBerry Limited. This project is not affiliated with or endorsed by BlackBerry.

Metadata

Release files for qnx-blueprint 0.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qnx-blueprint 0.3.2
File Size Uploaded Provenance Actions
qnx_blueprint-0.3.2.tar.gz 5.8 MB With provenance Details for qnx_blueprint-0.3.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qnx-blueprint 0.3.2
File Interpreter ABI Platform Actions
qnx_blueprint-0.3.2-py3-none-any.whl Python 3 none any Details for qnx_blueprint-0.3.2-py3-none-any.whl

Total release size: 11.8 MB

Release files / qnx_blueprint-0.3.2.tar.gz

Download URL qnx_blueprint-0.3.2.tar.gz
Size 5.8 MB
Tags Source
SHA-256 checksum
How to use checksums
3830c0509419d493d7f6d3c5f27e106ef32a99f929b9a06ee4c1ff2a85a01c6a
BLAKE2b-256 checksum
How to use checksums
49a216f097afa250008547caa938f51ab5820d938984f365a0df71621cbfcb9e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / qnx_blueprint-0.3.2-py3-none-any.whl

Download URL qnx_blueprint-0.3.2-py3-none-any.whl
Size 5.9 MB
Tags Python 3
SHA-256 checksum
How to use checksums
fc1dbfe505f614d37cf8ee1198825b4f6ed046ff4a1b9847e331c4ff1302f2ab
BLAKE2b-256 checksum
How to use checksums
ba3866eb697d14160fc6f5b3b8c504d23d8f6da91a9749c63435065f24c6694d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for qnx-blueprint 0.3.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for qnx_blueprint-0.3.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page