Fissure PwnDoc connector
This document describes the connector that pushes Fissure findings
into a self-hosted PwnDoc instance (https://github.com/pwndoc/pwndoc)
and optionally pulls the generated Docx report. The connector ships as
src/fissure_pwndoc.c (auth, mapping, push, report
download), src/fissure_pwndoc_cfg.c (persisted config) and
src/fissure_pwndoc_job.c (background worker), with the
regression tests tests/test_pwndoc.c, tests/test_pwndoc_cfg.c and
tests/test_pwndoc_job.c. The PwnDoc API contract below was read from the
v1.5.0 backend source (backend/src/routes and backend/src/lib/auth.js),
not guessed.
The connector is gated behind a Settings toggle (disabled by default) and exposed through explicit user actions (push findings / pull report); it never runs on its own. It only ever talks to an operator-configured, authorized PwnDoc host.
1. Product decisions
- Integration mode: push LIVE findings to a PwnDoc audit via the REST API (idempotent create/update), then OPTIONALLY trigger Docx generation and download the file. We do not merely upload a pre-rendered report (PwnDoc has no generic report-upload endpoint).
- Credentials: the password is resolved at login in this order: the
in-memory session password (the Settings field, or the control-API
request body), then the FISSURE_PWNDOC_PASSWORD environment variable,
then the first line of the
pwndoc.secretfile under the config dir. A raw JWT can be supplied instead (fissure_pwndoc_set_token, else FISSURE_PWNDOC_TOKEN). The password is NEVER written into the config file (section 5). - Severity mapping: synthesize a representative CVSS v3.1 AND CVSS v4.0 vector per Fissure severity band so PwnDoc's computed severity matches ours, and also set the PwnDoc priority. (PwnDoc derives a finding's severity from its CVSS vector.)
- Audit selection: match an existing audit by EXACT name (from GET /api/audits); create one with the configured defaults when there is no match. (No GUI audit picker.)
- Idempotency key storage: the
references[0]sentinelfissure-key:<dedup_key>is ALWAYS written and matched; when an idempotency custom field is configured, the same sentinel is also written into that PwnDoc custom field and matched on top (section 4.2).
2. PwnDoc v1.5.0 API contract (verified from source)
All paths are under /api. The backend is an Express +
MongoDB app.
2.1 Authentication (cookie-based JWT, not bearer)
PwnDoc's auth middleware (backend/src/lib/auth.js) reads the JWT ONLY
from a cookie named token, whose value is the string
JWT <jwt> (literal "JWT", a space, then the token).
It does NOT read Authorization: Bearer. The refresh token
is a separate cookie. This dictates the connector's transport handling:
capture Set-Cookie from the login response and resend the
cookies verbatim.
- POST
/api/users/token- body:
{ "username": string, "password": string, "totpToken": string? } - response body:
{ "token": <jwt>, "refreshToken": <rt> }, and the server also setsSet-Cookie: token=JWT <jwt>andSet-Cookie: refreshToken=<rt>(httpOnly).totpTokenis required only when the account has 2FA enabled.
- body:
- GET
/api/users/refreshtoken- sends the
refreshTokencookie; returns a refreshedtoken(+ Set-Cookie). - Called on a 401 / token-expiry to renew without re-sending the password.
- sends the
- GET
/api/users/checktoken-> validates the current token (used by "Test connection"). - DELETE
/api/users/refreshtoken-> logout / revoke (best-effort on shutdown).
Connector handling: a tiny in-memory cookie store keyed by name
(token, refreshToken), populated from
Set-Cookie on login/refresh and attached as a
Cookie: header on every subsequent request. On a 401
(pd_request_auth, and the report download), the connector refreshes once
and retries the request once. If the refresh fails, the original 401 is
reported; there is no automatic re-login with credentials.
2.2 Audits
- GET
/api/audits(permaudits:read) -> array of audit summaries (_id,name,language,auditType,company,createdAt,state, ...). Query:findingTitle,type(default|multi|retest). - POST
/api/audits(permaudits:create)- body:
{ "name": string (req), "language": string (req), "auditType": string (req), "type": "default"|"multi"?, "parentId": string? } - response:
{ "message": "...", "audit": { "_id": ... } }.
- body:
- GET
/api/audits/:auditId(permaudits:read) -> full audit incl.findings. - GET
/api/audits/:auditId/generate(permaudits:read) -> the Docx file download (filename<auditName>.<templateExt>).
2.3 Findings (the push target)
- POST
/api/audits/:auditId/findings(permaudits:update) - PUT
/api/audits/:auditId/findings/:findingId(permaudits:update) - DELETE
/api/audits/:auditId/findings/:findingId(permaudits:update)
Finding fields (from the Mongoose sub-schema in backend/src/models/audit.js):
| Field | Type | Notes |
|---|---|---|
title |
String | required |
vulnType |
String | vulnerability class/category label |
description |
String | |
observation |
String | |
remediation |
String | |
remediationComplexity |
Number 1..3 | |
priority |
Number 1..4 | |
references |
[String] | |
cvssv3 |
String | a CVSS:3.x vector string; PwnDoc derives severity from it |
cvssv4 |
String | optional CVSS v4 vector |
poc |
String | proof of concept (rich text) |
scope |
String | affected scope/asset |
status |
Number 0..1 | 0 = done, 1 = open (default 1) |
category |
String | |
customFields |
[customField] | site-specific extra fields |
identifier |
Number | PwnDoc-assigned incremental id (read-only) |
2.4 Vulnerabilities (knowledge base, optional)
- GET
/api/vulnerabilitiesand GET/api/vulnerabilities/:locale(permvulnerabilities:read). - POST
/api/vulnerabilities(permvulnerabilities:create): an array of vulns, each withcvssv3?,cvssv4?,priority?,remediationComplexity?,category?, and a requireddetailsarray of per-locale entries{ locale, title (req), vulnType?, description?, observation?, remediation?, references?, customFields? }. - Not used by the connector: it pushes audit findings directly and never writes the vuln knowledge base.
3. Fissure-side architecture
Fissure is a native C99 app built on Nilorea; the connector speaks PwnDoc's REST API through the existing HTTP stack:
- Transport:
fissure_request/fissure_engine(the same core the scanner and Repeater use) supports method, URL, custom headers (fissure_request_add_header), a JSON body (FISSURE_BODY_JSON), per-requesttls_verify(for self-signed hosts), and an upstream proxy. Responses expose status + headers (so we can readSet-Cookie) + body. - JSON: cJSON is already linked (used by the report and session layers).
- Findings model:
FISSURE_FINDING+ theFISSURE_FINDINGSstore; the report model (fissure_report) already resolves capture-backed evidence and redaction.
Business-logic modules (Fissure owns these; they are not
infrastructure for Nilorea): src/fissure_pwndoc.c/.h,
src/fissure_pwndoc_cfg.c/.h,
src/fissure_pwndoc_job.c/.h.
FISSURE_PWNDOC_CFG(fissure_pwndoc_cfg): the persisted fields enabled, tls_verify, base_url, username, audit_name, language, audit_type, company, idempotency_field. No credential is stored in it.FISSURE_PWNDOCsession (opaque, fissure_pwndoc_new / fissure_pwndoc_free): borrows aFISSURE_CONFIG(transport) and is configured through setters (fissure_pwndoc_set_base_url, _set_credentials, _set_token, _set_secret_file, _set_tls_verify, _set_defaults, _set_idempotency_field); holds the in-memory password/token, the cookie store (token, refreshToken) and the selected audit id.- Functions (each returns a status + fills an error string; all use
the transport core, all log via n_log):
fissure_pwndoc_login(), POST /users/token, capture cookies; handle TOTP.fissure_pwndoc_refresh(), GET /users/refreshtoken on expiry.fissure_pwndoc_test_connection(), login + checktoken; returns ok or the reason.fissure_pwndoc_select_or_create_audit(), GET /audits, match by name; else POST /audits with the configured defaults.fissure_pwndoc_push_findings(), map + idempotent create/update (below);fissure_pwndoc_push_json()is the same push over pre-mapped payloads (used by the background job).fissure_pwndoc_finding_json(), the mapping of one finding (section 4).fissure_pwndoc_generate_report(), GET /audits/:id/generate -> save .docx.
- There is no mock-transport seam: every request goes through the real
fissure_request_executepath (a static pd_request / pd_exec helper). The tests instead run a loopback fake PwnDoc HTTP server on a thread (tests/test_pwndoc.c server_fn) and point the connector's base URL at it, so Set-Cookie capture, Cookie resend and the JSON bodies are exercised end to end.
4. Finding mapping (FISSURE_FINDING -> PwnDoc finding)
Explicit, table-driven, and easy to extend (one mapping function with a clear per-field block):
| PwnDoc field | Source in Fissure | Transform |
|---|---|---|
title |
finding->title |
verbatim |
vulnType |
finding->category |
verbatim |
category |
finding->category |
verbatim |
description |
finding->description |
verbatim |
observation |
finding->evidence (redacted) or capture excerpt |
resolved like the report (redaction + truncation apply) |
poc |
request/response capture (request_ref/response_ref) | redacted reconstruction, as the report's request
field |
remediation |
finding->remediation |
verbatim |
references |
dedup_key sentinel, then finding->cwe,
finding->owasp |
fissure-key:<dedup_key> first (idempotency,
section 4.2), then non-empty cwe/owasp |
scope |
host/URL from finding->location |
parsed host or full URL |
cvssv3 |
finding->severity |
synthesized CVSS:3.1 vector per band (below) |
cvssv4 |
finding->severity |
synthesized CVSS:4.0 vector per band (below) |
priority |
finding->severity |
info/low->1, medium->2, high->3, critical->4 |
status |
always 1 (open) on create | left untouched on update |
4.1 Severity -> CVSS synthesis (v3.1 and v4.0)
A representative base vector per band whose score lands in the
matching CVSS range, so PwnDoc shows the same severity we assigned. Both
cvssv3 and cvssv4 are emitted as vector
strings; PwnDoc computes the score/severity from them.
CVSS v3.1 (scores are stable, shown in parentheses):
| Fissure severity | v3.1 band | example vector |
|---|---|---|
| critical | 9.0-10.0 | CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H (9.8) |
| high | 7.0-8.9 | CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:U/C:H/I:H/A:N (8.2) |
| medium | 4.0-6.9 | CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:U/C:L/I:L/A:N (5.4) |
| low | 0.1-3.9 | CVSS:3.1/AV:N/AC:H/PR:L/UI:R/S:U/C:L/I:N/A:N (3.1) |
| info | 0.0 | CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:N (0.0) |
CVSS v4.0 (the base score is a MacroVector table lookup, not a formula, so the vectors are tuned to land in the band; the connector asserts the band at build time and the table is the single place to refine them):
| Fissure severity | v4.0 band | example vector |
|---|---|---|
| critical | 9.0-10.0 | CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N |
| high | 7.0-8.9 | CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:P/VC:H/VI:H/VA:N/SC:N/SI:N/SA:N |
| medium | 4.0-6.9 | CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:P/VC:L/VI:L/VA:N/SC:N/SI:N/SA:N |
| low | 0.1-3.9 | CVSS:4.0/AV:N/AC:H/AT:P/PR:L/UI:P/VC:L/VI:N/VA:N/SC:N/SI:N/SA:N |
| info | 0.0 | CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:N/VI:N/VA:N/SC:N/SI:N/SA:N |
These vectors are a clearly-documented stand-in driven by severity, not measured metrics; the mapping table is the single place to refine them.
4.2 Idempotency
PwnDoc findings carry no external key, so re-pushing would duplicate.
The connector embeds Fissure's dedup_key as a sentinel
reference fissure-key:<dedup_key> (the first entry of
the finding's references array). On push it GETs the audit,
indexes existing findings by scanning their references for that
sentinel, and PUT-updates a match or POST-creates otherwise. Result:
re-running a scan-and-push converges instead of accumulating
duplicates.
The references sentinel is always written and always a matching key, because it is instance-agnostic and needs no setup. A CustomField can be used as an additional matching key: set FISSURE_PWNDOC_CFG.idempotency_field (the "Idempotency field id" Settings row, persisted in pwndoc.json) to a PwnDoc CustomField label OR id. All custom-field handling lives in fissure_pwndoc_push_json (which runs on the worker with network access, so it works for both the synchronous and the async-job paths):
- Discovery: pd_resolve_custom_field_id GETs
/api/data/custom-fieldsand resolves the configured value to the field's_idby matching itslabel(case-insensitive) or_id. On any failure (missing endpoint, different shape) it falls back to using the configured value verbatim as the id, so discovery never breaks a push. - Write: each pushed finding gets the
fissure-key:<dedup_key>sentinel injected into acustomFieldsentry ({ customField: <resolved id>, text: <sentinel> }) just before the PUT/POST. - Match: pd_existing_finding_id matches an existing finding by its
references sentinel OR by a customFields entry whose
customField(id string or populated definition object) is the resolved id and whosetextis the key, so the custom field works as a primary match key even on instances that drop references.
Because references are always written and matched too, a
wrong/empty/unresolved field id can never break idempotency or create
duplicates. test_pwndoc drives the loopback fake's
/api/data/custom-fields plus an existing finding that
carries the key only in a customField, and asserts: the NAME resolves to
the id, that finding is matched and updated via its custom field (no
references), and a created finding's POST body carries the resolved id +
key in customFields.
5. Settings / configuration layer
Settings persistence and the Settings view shipped
(fissure_config load/save +
fissure_gui_settings), and the connector itself is built on
top of them (fissure_pwndoc,
fissure_pwndoc_cfg, fissure_pwndoc_job,
POST /api/report/pwndoc, tests/test_pwndoc +
test_pwndoc_cfg). This section documents the PwnDoc-specific part.
Persisted by fissure_pwndoc_cfg in its own file,
<config>/pwndoc.json (not in
fissure.conf), as a flat JSON object with unprefixed
keys:
| Key | Meaning | Default |
|---|---|---|
enabled |
master on/off for the integration | 0 (off) |
tls_verify |
verify the PwnDoc TLS cert (self-signed -> 0) | 1 |
base_url |
e.g. https://pwndoc.lan |
unset |
username |
login user | unset |
audit_name |
target audit name (matched exactly, or created) | unset |
language |
default audit language (e.g. en) |
unset |
audit_type |
default audit type/template name | unset |
company |
company/client label | unset |
idempotency_field |
PwnDoc CustomField label or id that also receives the dedup key | unset |
NOT persisted in the config: the password. Implemented resolution at
login time, in order: the Settings session field (held in memory as
FISSURE_APP.pwndoc_password) when set, else the
FISSURE_PWNDOC_PASSWORD environment variable, else the
first line of the pwndoc.secret file (0600) under the
config dir. The Settings popup manages the secret file: "Save password
to file" (writes the password field 0600 via
fissure_pwndoc_save_secret), "Clear file" (deletes it), and a "Password
file: stored/none" indicator.
Token mode: a raw JWT supplied via FISSURE_PWNDOC_TOKEN
(or fissure_pwndoc_set_token) authenticates directly, login installs it
as the token cookie and skips the /api/users/token call, so
no username/password is needed. There is no refresh in this mode (an
expired token just fails).
6. GUI integration (implemented)
The connector config is persisted (no password) by fissure_pwndoc_cfg
to <config>/pwndoc.json; the app owns it
(FISSURE_APP.pwndoc) and a session-only password lives in memory
(FISSURE_APP.pwndoc_password). fissure_gui_main_pwndoc_session builds a
configured FISSURE_PWNDOC from the app for all three actions.
- Settings popup: a "PwnDoc integration" section (enable toggle, base URL, username, masked session-only password, audit name, Verify-PwnDoc-TLS toggle) with a "Test connection" button that runs fissure_pwndoc_test_connection and shows OK / the server's error, persisting the non-secret fields.
- Findings view: a "Push to PwnDoc" button (selects/creates the audit named in the config and pushes the findings store, reporting created/updated/failed).
- Report view: a "PwnDoc report" button (generates the Docx on PwnDoc and downloads it via a save dialog).
- All three are gated on the enable toggle. Push and report generation run on a background worker (fissure_pwndoc_job): the job snapshots the config + the mapped finding payloads on the GUI thread, then does the network on a worker thread; the view polls fissure_pwndoc_job_done each frame and shows the result. Test connection stays synchronous (a single quick round-trip).
7. Robustness
- Timeouts from the transport config (default and connect timeouts). There is no retry or backoff on 5xx or connection errors: such a request fails and the reason is reported. The only retry is a single auth-refresh-and-retry on 401.
- Pagination:
/api/auditsreturns the full set in v1.5.0; if a future version paginates, follow it. Findings are read whole from the audit document. - Clear logging: one line per operation (host, audit, counts, status), secrets redacted. Errors surface a short reason to the GUI and a fuller line to the log.
8. Testing
- tests/test_pwndoc.c: a loopback fake PwnDoc server (no live PwnDoc) returns canned login/audit/finding responses to the real connector + transport. It covers login (good/bad credentials, env and secret-file password, token mode, TOTP), audit select/create, the mapping, create vs update by dedup key, the custom-field idempotency path, cookie reuse, and report download writing a file.
- tests/test_pwndoc_cfg.c:
pwndoc.jsonload/save round trip and defaults. - tests/test_pwndoc_job.c: the background push/report worker.
- No secrets in the repo or test fixtures; the fake uses placeholder tokens.
9. Security and ethics
- Disabled by default; only an explicit operator action pushes anything.
- Credentials never committed and never written to fissure.conf;
env/secret-file precedence documented (section 5).
.gitignorecoverspwndoc.secretand*.docxdownloads. - Self-signed hosts are supported via the TLS-verify toggle, off by choice, with the same warning posture as the rest of the tool.
- Pushing findings sends scan data to an external service; it happens only on the user's explicit action against a host they configured.
10. Build, docs, and phasing
Build: the connector sources are picked up by the
src/*.c wildcard; the tests/test_pwndoc, test_pwndoc_cfg
and test_pwndoc_job rules run under make tests, and the
sources are covered by make checks.
Usage (configure PwnDoc): the PwnDoc account needs
audits:read, audits:create and
audits:update. Set the host, user and audit name in the
Settings "PwnDoc integration" section (or pass them in the
POST /api/report/pwndoc body), supply the password as
described in section 5, then: Test connection -> scan -> Push to
PwnDoc -> PwnDoc report.
11. Design decisions
- Audit selection: match an existing audit by EXACT name (GET
/api/audits), and create one with the configured defaults when there is
no match. There is no GUI audit picker (section 1, section 3
select_or_create_audit). - Idempotency key storage: the
references[0]sentinelfissure-key:<dedup_key>is always written and matched; a configured custom field receives the same sentinel and is matched in addition (section 4.2). - CVSS v4: emit a synthesized
cvssv4vector per band alongsidecvssv3(section 4.1), not left empty.