Fissuredocumentation v5.3.1
On this page

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.secret file 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] sentinel fissure-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.

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 sets Set-Cookie: token=JWT <jwt> and Set-Cookie: refreshToken=<rt> (httpOnly). totpToken is required only when the account has 2FA enabled.
  • GET /api/users/refreshtoken
    • sends the refreshToken cookie; returns a refreshed token (+ Set-Cookie).
    • Called on a 401 / token-expiry to renew without re-sending the password.
  • 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 (perm audits:read) -> array of audit summaries (_id, name, language, auditType, company, createdAt, state, ...). Query: findingTitle, type (default | multi | retest).
  • POST /api/audits (perm audits:create)
    • body: { "name": string (req), "language": string (req), "auditType": string (req), "type": "default"|"multi"?, "parentId": string? }
    • response: { "message": "...", "audit": { "_id": ... } }.
  • GET /api/audits/:auditId (perm audits:read) -> full audit incl. findings.
  • GET /api/audits/:auditId/generate (perm audits:read) -> the Docx file download (filename <auditName>.<templateExt>).

2.3 Findings (the push target)

  • POST /api/audits/:auditId/findings (perm audits:update)
  • PUT /api/audits/:auditId/findings/:findingId (perm audits:update)
  • DELETE /api/audits/:auditId/findings/:findingId (perm audits: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/vulnerabilities and GET /api/vulnerabilities/:locale (perm vulnerabilities:read).
  • POST /api/vulnerabilities (perm vulnerabilities:create): an array of vulns, each with cvssv3?, cvssv4?, priority?, remediationComplexity?, category?, and a required details array 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-request tls_verify (for self-signed hosts), and an upstream proxy. Responses expose status + headers (so we can read Set-Cookie) + body.
  • JSON: cJSON is already linked (used by the report and session layers).
  • Findings model: FISSURE_FINDING + the FISSURE_FINDINGS store; 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_PWNDOC session (opaque, fissure_pwndoc_new / fissure_pwndoc_free): borrows a FISSURE_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_execute path (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-fields and resolves the configured value to the field's _id by matching its label (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 a customFields entry ({ 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 whose text is 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/audits returns 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.json load/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). .gitignore covers pwndoc.secret and *.docx downloads.
  • 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] sentinel fissure-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 cvssv4 vector per band alongside cvssv3 (section 4.1), not left empty.