what the scanners catch

Two static analyzers run as GitHub Actions workflows on every push to main and on every pull request:

• Semgrep with --config=auto, which pulls a registry-managed rule set covering common security and correctness patterns across many languages.
• CodeQL with the security-extended query suite, run separately for Python and JavaScript/TypeScript.

Both write SARIF (and JSON, in Semgrep's case) and upload the results as workflow artifacts. The reports are public — anyone can download the artifacts from any run, since the repository is public.

Why this matters for pq-share specifically: the application intentionally exposes weak primitives in its picker. Selecting AES-128-GCM or Ed25519 alone or X25519-only is not a bug — it's the demonstration. A naive read of the SAST output would say "look at all these weak ciphers!" The honest read, below, is more nuanced.

Four initial findings total across two scanners and roughly four thousand lines of code. By the standards of "auto-config Semgrep on a real codebase," that's quiet. By the standards of "demonstration application that intentionally offers weak cryptography for educational purposes," it's notable for what didn't appear.

One finding at a time, with the verdict and the reasoning. Three labels are used: tp for true positive (real issue), fp for false positive in this context, and policy for findings that depend on intent (the syntax is fine; the question is whether using this primitive for this purpose is appropriate).

async def _apply_column_additions(conn) -> None:
    for table, column, ddl in _PENDING_COLUMNS:
        rows = await conn.execute(text(f"PRAGMA table_info({table})"))
        existing = {row[1] for row in rows.fetchall()}
        if column not in existing:
            await conn.execute(text(f"ALTER TABLE {table} ADD COLUMN {column} {ddl}"))

log.info("sent email to=%s subject=%r via %s", to, subject, settings.smtp_host)

sessionStorage.setItem(SS.WRAPPED_BLOB, wrappedB64);

pq-share's picker offers five options for key exchange and five for digital signatures. A naive observer would expect a SAST scan to flag most of these — they include X25519 alone (no PQ hedge), ECDSA-P256 (broken by Shor's algorithm in polynomial time on a CRQC), AES-128-GCM (Grover-reducible to 64-bit effective security), and so on. Zero of those primitives were flagged by either scanner.

Why? Because the picker uses every primitive correctly. Each call site is a well-formed invocation of a vetted library:

// frontend/crypto.js
export function ed25519Sign(message, priv) { return ed25519.sign(message, priv); }
export function aesGcmSeal(key, plaintext) {
  const cryptoKey = await crypto.subtle.importKey("raw", key, "AES-GCM", false, ["encrypt"]);
  const iv = crypto.getRandomValues(new Uint8Array(12));
  ...
}

There is no AES.MODE_ECB, no hardcoded key, no reused IV, no missing authentication tag. SAST tools detect syntactic patterns — constructs that are wrong on their face. The weakness pq-share is demonstrating is at a different layer: it's a policy question of whether a given primitive is appropriate for a given threat model. Ed25519 is a perfectly correct EdDSA implementation; it is also forgeable by a sufficiently large quantum computer. Both statements are true. SAST tools can verify the first, not the second.

Each item in the right column is a real consideration in pq-share's threat model — and each is documented openly in the user guide's threat model section. The right tool to catch them is not a SAST scanner; it's an explicit policy: "this codebase declares what it considers acceptable, and any contributor can read the list." pq-share's CryptoSuite Pydantic schema and PRESET_LOCKS table do exactly that. They enumerate which primitive combinations are permitted under which regulatory claim, and the validator rejects any upload that lies about which preset it satisfies.

Three things, in increasing order of nuance.

1. SAST is high-leverage for syntactic mistakes

Of pq-share's four findings, two correspond to real patterns that would become bugs under predictable refactors (the text() migration code) or would benefit from a structural mitigation (log sanitization). One was a heuristic match driven by misleading naming. None of these would have surfaced without a scanner. Run them. Triage the output. Don't ignore findings just because the current call site happens to be safe.

2. SAST cannot reason about appropriateness

The same scanners would, on most production codebases, generate dozens or hundreds of findings about weak crypto patterns — but only when the patterns are syntactic. A correct use of a weak primitive looks identical, on the wire and in the AST, to a correct use of a strong one. The decision lives in the threat model, not the source. Pair SAST with explicit policy enumeration.

3. The educational value of pq-share's findings is the gap

pq-share's whole point is that the choice of cipher suite is the subject of the demonstration. The picker exposes every primitive openly. Off-the-shelf SAST does not flag any of them, because there's nothing wrong with how they're used — only with whether they should be used at all, and that's not a question SAST is built to answer.

If you're shipping a real product, the lesson is to add project-specific rules — Semgrep can write custom YAML rules against the abstract syntax tree, CodeQL has its own query language for this — that encode your policy. Forbid the picker's "AES-128-GCM" string literal in production code paths. Forbid the Ed25519 sole-sig preset in any preset that isn't labeled "demo." The scanner becomes a guardrail for human judgment, not a substitute for it.

Both scanners run on every push to the public repo. To run the same scans locally:

Semgrep

pip install semgrep
cd path/to/pq-share
semgrep --config=auto --json-output=semgrep.json --sarif-output=semgrep.sarif

CodeQL

# Install the CodeQL CLI from
# https://docs.github.com/en/code-security/codeql-cli
cd path/to/pq-share
codeql database create --language=python --source-root=. db-py
codeql database analyze --format=sarif-latest --output=python.sarif \
    db-py codeql/python-queries:codeql-suites/python-security-extended.qls

codeql database create --language=javascript --source-root=. db-js
codeql database analyze --format=sarif-latest --output=javascript.sarif \
    db-js codeql/javascript-queries:codeql-suites/javascript-security-extended.qls

From CI artifacts

Or download the latest CI artifacts directly with the GitHub CLI:

gh run list --limit 5 -R harpoonsecurity/pq-share
gh run download <run-id> -R harpoonsecurity/pq-share

That writes four directories — semgrep-results-json/, semgrep-results-sarif/, codeql-results-python/, codeql-results-javascript-typescript/ — each with the corresponding raw output. Artifacts are retained for 90 days per run.

• pq-share user guide — the application itself, eight keypairs, picker walkthrough, threat model
• Semgrep workflow definition
• CodeQL workflow definition
• Semgrep registry — the rules --config=auto pulls from
• CodeQL query help — what each rule looks for, with examples
• CodeQL CLI — for running the analysis locally