Blueprint
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.
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.
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
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-lossinstead 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 inread(). - 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_PRIORITYchannels. 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.
--explainandinit --reviewcallclaude-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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.