Security Policy & Threat Model¶
What primr is (and isn't), security-wise¶
primr is an LLM-API client + adaptive web scraper + MCP/A2A agent. It does not train, fine-tune, host, or serve models - the models are third-party hosted APIs (Gemini, Grok, OpenAI, Anthropic, AWS Bedrock, Azure/Microsoft Foundry, Ollama, and any OpenAI-compatible endpoint). Per primr's design philosophy, the model is a commodity; the orchestration pipeline is the asset.
That framing scopes the threat model. Whole categories of adversarial-ML security are out of scope by construction because primr owns no model weights or training pipeline: training-time poisoning/backdoors, model extraction/stealing, membership/attribute inference, model inversion, watermarking/weight protection, and confidential-compute/certified-robustness serving. If primr ever ships a hosted/served model, this section must be revisited.
The real attack surface is four things: (1) untrusted retrieved content flowing into prompts, (2) LLM output driving downstream actions, (3) the agentic MCP/A2A tool surfaces, and (4) provider secrets + the dependency supply chain.
Threat model (MITRE ATLAS-style, scoped to client/scraper/agent)¶
| # | Threat | Vector | Control(s) | Status |
|---|---|---|---|---|
| T1 | Indirect prompt injection | Instructions embedded in scraped pages / postings / sitemaps | sanitize_for_llm (injection-pattern + control-char stripping) + fence_untrusted data-fencing at the external-content→prompt boundaries. Fenced: insights extraction, deep research, the fast-run analysis-workbook and section-writer corpus/external-source blocks, hypothesis-tree inputs, gap-analysis summaries, report and strategy regeneration evidence, hiring-signal triage and JD extraction, the hiring-signal block entering the Deep Research stage-1 context (load-bearing for the verbatim File Search Store upload), the scraped-external and hiring-signal blocks inside insights.txt (which the AI-strategy prompt and the workbook-fallback section prompts read unfenced), and the scraped-adjacent strategy context artifacts (hiring signals, recon context). Sanitize-only (deliberately unfenced): website summarization and composer notes, where the surrounding framing is the instruction boundary. LLM-generated working artifacts (gap analysis, workbook) enter downstream prompts unfenced - the accepted "laundered injection" residual below |
Shipped |
| T2 | SSRF / internal pivot | Attacker page or redirect points primr at loopback / RFC1918 / link-local / cloud-metadata | is_safe_url on every egress helper; IP-pinned per-hop redirect validation through data/safe_http.py for fallback_sources._http_get, hiring_signals._http_get, Wayback CDX/replay fetches, async citation-resolution HEAD requests, the tiered httpx scraper, pooled HTTPClient GET/HEAD calls, the tiered requests scraper, and the curl_cffi scraper; browser egress planning for Chromium-backed tiers with initial-host resolver pins, local loopback egress proxying for dynamic browser hosts, QUIC disabled, and Playwright/Patchright request route guards; manual per-hop validation in data/scraping/net.py; SSRFGuardHook on tool calls |
Shipped |
| T3 | Secret leakage | API key in a log line, prompt, or persisted artifact | SecretMaskingFilter on all log handlers; mask_sensitive_data (incl. xAI) applied in chat_logger before persist; browser and A2A URL logs strip userinfo and query strings; research memory rejects secret-like payloads before durable YAML writes; company profiles reject URL userinfo and secret-like values before durable JSON writes; hardcoded-secret CI gate |
Shipped |
| T4 | Cost / resource exhaustion | Runaway tool invocation | CostGuardHook budget; estimate_run/A2A estimate_research first; PRIMR_ENFORCE_MCP_COST_CAPS; server-issued approval tokens for MCP cost-cap-governed tools and A2A research execution; explicit budget-enforcement payloads; MCP and A2A runtime budget propagation for fast optional stages and non-fast optional strategy documents; eval batches reserve each started cell's planning estimate across per-run counter resets; Accordion counts its accepted Deep Research task and direct Gemini section usage before later sections; run manifests and compact usage summaries expose approved ceiling, active checkpoint status, and non-interruptible required provider tasks without manifest bodies; remote skill-pack icons require --remote-icons / remote_icons; integrated vendor-research refresh requires estimate-bound --refresh-vendor-research, preflights every required provider, serializes shared-client refresh work, records completed provider tasks before atomic cache publication, and overrides ambient refresh off; direct cache generation aggregates every selected task in a zero-call dry-run, enforces --budget, requires interactive or explicit noninteractive approval, and returns nonzero on partial failure; Gemini PDF extraction defaults to local PyMuPDF unless PRIMR_PDF_LLM_MAX_CALLS is set; single-job model; rate limiting |
Shipped, with required Deep Research tasks still estimate-gated mid-flight |
| T5 | Unauthorized tool access | Calling MCP/A2A tools without/with stale creds | JWT (HMAC-SHA256, constant-time, finite expiry/nbf/aud validation, fail-closed explicit scope claims), admin-token hashing with uncached max-age enforcement, loopback-only unauthenticated MCP HTTP and A2A, and shared MCP/A2A bearer-token context for authenticated A2A requests | Shipped |
| T6 | Output egress / scope expansion | Injected instruction tries to widen URL/tool scope or exfiltrate | All fetches gated by T2; the LLM cannot register tools or bypass is_safe_url (tested invariant); lite, standard, and asynchronous strategy context accepts only bounded regular files, rejects symbolic links, hard links, reparse points, oversized inputs, and validation-time mutation, then uploads or reads a private stable snapshot that is removed after the provider call |
Shipped |
| T7 | Supply-chain compromise | Vulnerable/malicious dep or tampered release | PR/push and weekly scheduled pip-audit + Trivy gates; bandit; uv.lock; hash-verified lock exports for production containers; OIDC publishing; SLSA build-provenance; manually reviewed dependency updates |
Shipped |
| T8 | Per-tool privilege separation | Low-trust client invokes a high-cost/admin tool | Per-tool MCP scope policy (read, report, research, delegate, admin) enforced at dispatch and report-resource readback; A2A skill dispatch enforces the shared read/report/research split for estimate, status, health, compact resources, report reads, research, QA, and cancellation; OAuth scope / Entra scp claims honored; legacy write tokens retained for compatibility for research/delegate only and does not satisfy report; matching approval tokens and cost caps are required by default for cost-governed execution on every MCP transport and for A2A research execution, with only an explicit false PRIMR_ENFORCE_MCP_COST_CAPS value retained as an unsafe compatibility opt-out; privacy-preserving agent audit log with admin-readable MCP tool-call events, MCP resource-read events, and A2A skill-call events, each carrying a stable request_id and body-free otel_span projection; ownership-gated job artifact metadata via primr://output/artifacts/by_job/{job_id}, QA summary metadata via primr://output/qa_summary/by_job/{job_id}, usage/cost summary metadata via primr://output/usage_summary/by_job/{job_id}, source appendix metadata via primr://output/source_summary/by_job/{job_id}, scrape trace metadata via primr://output/trace_summary/by_job/{job_id}, verification metadata via primr://output/verification_summary/by_job/{job_id}, and calibration metadata via primr://output/calibration_summary/by_job/{job_id} without report body content; explicit report-body reads go through primr://output/report/by_job/{job_id} and A2A read_report_by_job with ownership checks, report scope for HTTP callers, and content_mode / artifact_type / max_chars output negotiation; check_jobs, primr://output/latest, and primr://output/by_job/{job_id} no longer return report bodies or previews to authenticated HTTP callers even when they hold report; A2A check_jobs returns compact artifact/report resource URIs instead of raw output paths; resource-read audit events store normalized resource kind, hashed URI, hashed result body, job id when present, granted scopes, duration, outcome, request id, and span-safe attributes without raw URI query values or resource bodies; A2A skill-call events store transport, skill name, hashed message/result payloads, hashed caller id, granted scopes, duration, outcome, job id when present, request id, span-safe attributes, and sanitized estimate/cap metadata without raw message text, task ids, URLs, report paths, approval tokens, raw results, or caller ids; trace summaries omit raw trace entries, URLs, and page content, verification summaries omit raw claims, source URLs, search queries, and explanations, and calibration summaries expose counts including inference source-copy counts while omitting raw claims, source URLs, evidence reviews, and rationales |
Shipped (MCP Stages 1-3 plus all seven artifact-resource slices, MCP report-read scope separation, resource-read audit, A2A skill scopes, A2A skill-call audit, A2A compact-resource parity, A2A report-read parity, and A2A research approval/budget parity) |
Portable Agent Plugin boundary¶
The experimental agent-plugin/ package contains public manifests, skills,
and a local stdio MCP declaration. It embeds no provider credentials, OAuth
configuration, environment values, or fixed authorization headers. Agent
Plugins v1 does not define portable OAuth or credential-reference fields, and
its configured env or HTTP headers are visible package data rather than a
secret channel. Primr therefore leaves credential discovery and storage to the
client and its normal process environment.
The package's MCP entry uses the bare primr executable token with mcp as a
separate argument. A client resolves that token using its executable search
rules. Server startup or authentication failure disables that component, not
the packaged skills, and never authorizes a research run. Provider-backed work
still crosses Primr's estimate, approval, scope, and runtime budget gates.
Collection resource boundaries¶
The existing pinned Requests adapter and HTTPX transport bound response bodies before SDK buffering, redirect handling, or status-retry draining. Curl uses a synchronous raw callback rather than its background streaming queue. These paths share the bounded identity/gzip/deflate decoder. Ordinary page responses have an 8 MiB wire and decoded-body ceiling; sitemap requests use their configured document ceiling. Unsupported content encodings and malformed compressed framing fail closed. Caller headers, cookies, Host/SNI pinning, and redirect validation remain in their existing owners.
Sitemap discovery defaults to 32 attempted documents, including failed or empty roots and children, a shared 100 MiB received/expanded-content allowance, and a 60-second discovery deadline. Each document is limited to 50 MiB, one million XML elements, and 64 levels of XML nesting. Incremental defusedxml parsing clears processed records and retains entity restrictions. Depth and successful-URL limits remain independent; empty children spend the attempted-document budget. The HTTP adapter charges the larger wire/decoded representation for every redirect and status-retry response. Sitemap expansion adds any further increase to that charge. An attempt reserves its allowance before I/O; a failed read or expansion retains the reservation when completed work cannot be measured safely. Only successful bounded reads/expansions refund unused capacity.
HTML extraction rejects trees above 100,000 nodes or depth 128 before its pruning/scoring passes. Both main-content scorers use one iterative subtree metrics pass, preserving text weights, link density, and document-order ties.
Local PDF extraction uses one short-lived Python child, separate from the research job scheduler. The child inherits job cancellation ownership and is killed and reaped on timeout or parent interruption. Before importing PyMuPDF, it installs a 1 GiB OS memory limit (Linux address space or Windows process memory) and a POSIX CPU limit. Darwin adds the 1 GiB allocation allowance to the worker's existing virtual mappings; inherited stricter limits are retained. Extraction accepts at most 20 MiB, visits at most 200 pages, retains at most 250,000 characters, and has a 12-second parent wall timeout. Truncated output carries an explicit marker. Unsupported resource controls, parser crashes, and timeouts fail closed. Native diagnostics cannot fill the result pipe, and provider credentials are excluded from the child's environment. First-party recovery retains its tighter input/output limits.
Playwright and Patchright launches explicitly set chromium_sandbox=True by
default, including persistent profiles, channel retries, and fresh-browser
fallbacks. Merely omitting --no-sandbox does not enable these SDKs' sandbox.
Ubuntu's AppArmor restrictions can block downloaded browser binaries from
creating sandbox namespaces. Linux CI loads a browser-cache-specific profile,
following Chromium's guidance,
so the native gate exercises sandboxed launches without changing global policy.
An operator on a host without sandbox support may explicitly set
PRIMR_DISABLE_CHROMIUM_SANDBOX=1; launch failure never triggers that opt-out.
Network deadline checks run between blocking operations; DNS resolution and individual socket operations still depend on OS and transport timeouts. These collection budgets do not constitute a hard wall timeout for an entire research job. Browser rendering has separate runtime limits, and sandboxing does not establish that the browser itself is free of vulnerabilities.
Residual risks (accepted)¶
- T1 is mitigated, not eliminated - a novel phrasing could evade the pattern set; the data-fence is the backstop, and an injection red-team eval is tracked.
- T1 laundered injection: LLM-generated working artifacts (gap analysis, the analysis workbook) are built FROM fenced scraped inputs but enter later prompts unfenced; an injection that survives into the model's own output re-enters downstream prompts as trusted text. Accepted because re-fencing model output would fence the pipeline's own analysis, and the upstream fences plus sanitization make survival unlikely; the red-team eval covers this path.
- T2 has complete pre-request SSRF validation and per-hop redirect validation on the shared safe HTTP seam, async citation HEAD requests, preflight website HEAD checks, provider-hosted skill-pack image fetches, discovery HTTP helpers, pooled HTTPClient GET/HEAD calls, and the tiered requests/httpx/curl_cffi scrapers. Workday hiring-signal JSON POST probes now drop redirects rather than following an unvalidated hop. The shared safe HTTP seam, tiered httpx scraper, pooled HTTPClient, tiered requests scraper, and curl_cffi scraper now resolve each hop once, validate every returned address, and pin the actual connection target while preserving the public hostname semantics each client needs for virtual hosting and TLS. Browser-backed Chromium tiers now pin the initial hostname with Chromium resolver rules and force browser traffic through a local loopback egress proxy. The proxy validates each HTTP request or HTTPS CONNECT target, dials the validated IP literal, and tunnels TLS without terminating it, while Playwright-compatible route guards remain as defense-in-depth. QUIC is disabled for proxied browser launches so browser traffic stays on the TCP proxy path.
- T8 Stages 1-3 are shipped for MCP tool dispatch and resource reads:
per-tool scopes, server-issued approval tokens, and structured audit events. The
first seven job-scoped artifact-resource slices are also shipped:
primr://output/artifacts/by_job/{job_id}returns metadata only for an owned job, andprimr://output/qa_summary/by_job/{job_id}returns compact QA score/status/count metadata without detailed QA body text, andprimr://output/usage_summary/by_job/{job_id}returns compact manifest cost, timing, approval, execution, and artifact-count metadata without company URLs, approval tokens, manifest artifact lists, or full manifest content, andprimr://output/source_summary/by_job/{job_id}returns compact citation/source appendix metadata without report body content, andprimr://output/trace_summary/by_job/{job_id}returns compact scrape trace metadata without URLs, final URLs, raw trace entries, or page content, andprimr://output/verification_summary/by_job/{job_id}returns compact claim verification trust score, claim counts, status counts, first-party downgrade counts, and source-reference counts without raw claims, source URLs, search queries, explanations, or report body content, andprimr://output/calibration_summary/by_job/{job_id}returns compact label-calibration per-label counts, inference source-copy counts, evidence-review count buckets, judge provenance, and judge-agreement metadata without raw claims, source URLs, evidence reviews, rationales, or report body content. MCP report-body reads now useprimr://output/report/by_job/{job_id}with ownership checks, explicitreportscope for authenticated HTTP callers, andcontent_mode/artifact_type/max_charsoutput negotiation. Remote QA, standalone strategies, and skill-pack file inputs also requirereportscope and the current job's exact artifact ownership. Directory reuse is limited to that job's dedicated directory; shared root ancestors and historical files without a retained owner record are rejected. Explicit remote destinations must be in an owned job directory; skill-pack calls that omit a destination receive a fresh server-selected directory. Local stdio and the trusted loopback A2A context retain contained operator file reuse. QA, nested skill-pack evidence, role briefs, and saved plans use bounded regular-file snapshots before parsing or provider processing. MCP roots follow the report configuration even when a source checkout is launched from a different working directory.check_jobs,primr://output/latest, andprimr://output/by_job/{job_id}omit report bodies or previews for all authenticated HTTP callers, even when they holdreport; A2Acheck_jobsreturns compact artifact/report resource URIs instead of raw output paths. All hide unowned jobs behind the same response as missing jobs. Resource-read audit events record normalized resource kind, hashed URI, hashed result body, job id when present, granted scopes, request id, span-safe attributes, duration, and outcome without raw URI query values, raw resource bodies, or raw caller ids. A2A authenticated requests now share the MCP auth context, enforceread/researchat skill dispatch, own jobs by tokenclient_id, enforcereportforread_report_by_job, and write skill-call audit events with hashed message/result payloads, hashed caller ids, granted scopes, request id, span-safe attributes, duration, outcome, and job id when present. A2Aestimate_researchnow issues approval-token fields, and A2Aresearch_companyenforcesmax_estimated_cost_usdplus a matching token by default before job creation, then propagates the accepted cap intoPipelineRunneras the runtime budget. Residual risk remains around required provider tasks that cannot be interrupted mid-flight after the user accepts the estimate. Approval tokens are single-use and process-instance-bound, so a restart requires a new estimate and fresh approval even when instances share a signing secret. Strategy generation validates the report as one stable, regular, non-linked file and gives providers only a verified private snapshot; a changed report fails before a provider call. Issue low-trust tokens with explicitreadscopes rather than relying on legacy no-scope JWT defaults, and issuereportonly to clients that should consume report text. - Chat logs and reports are persisted locally; protect
logs/and working dirs with normal filesystem permissions.
Supported Versions and Vulnerability Reporting¶
The root Security Policy is the canonical source for supported versions, private vulnerability reporting, response timelines, and disclosure scope. This document owns the detailed threat model and security controls.
Security Measures¶
Primr implements several security controls:
- SSRF Protection: All outbound URLs are validated against private IP ranges, cloud metadata endpoints, and DNS rebinding; migrated helpers also validate every redirect hop before connecting, the shared safe HTTP, requests-family, httpx scraper, and curl_cffi scraper seams pin connections to the validated address, and Chromium-backed browser tiers force browser traffic through the local pinned egress proxy while route-guarding unsafe requests where supported
- Input Sanitization: Company names and URLs sanitized against injection attacks
- JWT Authentication: Signed token verification for MCP HTTP mode
- Rate Limiting: Per-client request limits
- Security Headers: OWASP-recommended headers on all API responses
See SECURITY_OPS.md for operational security guidance.
Security Audits¶
- January 2026: Initial security review (XXE, SSRF fixes)
- February 2026: JWT verification, CORS hardening, input sanitization
- May 2026: AI/agent security posture - indirect prompt-injection fencing
(
fence_untrusted) at the insights-extraction, deep-research, and composer boundaries, sink-level secret redaction (SecretMaskingFilter) + chat-log redaction, egress-guardrail invariant tests across all fetch helpers, supply-chain gates (pip-audit, Trivy, bandit, SLSA provenance), and this scoped threat model. - July 2026: fencing extended to the remaining fast-run scraped-text→prompt
boundaries (workbook/section corpus blocks, hypothesis tree, gap-analysis
summaries, regeneration evidence, hiring triage/extraction,
insights.txtexternal block, strategy context artifacts); the T1 row now enumerates fenced vs sanitize-only boundaries instead of claiming blanket coverage. - July 2026: all remote GitHub Actions are pinned to verified commit SHAs and shipped Python container bases are pinned to a verified multi-platform digest. Deterministic fitness tests reject moving action tags and unpinned base images before merge.
- July 2026: standalone strategy estimates, approval tokens, and usage records share the canonical Deep Research planning cost. Cost-gated strategy calls explicitly suppress environment-driven vendor refreshes so one approval cannot silently authorize a second paid research task.
Acknowledgments¶
We appreciate responsible disclosure and will acknowledge security researchers who report valid vulnerabilities (with permission).
External supply-chain signals and certification¶
Maintain host and base-image CA stores independently of Python dependencies. The certifi security floor protects clients that use its bundle; native/system trust stores, user-supplied CA bundles, and pip's vendored trust bundle have separate owners and update paths. Rebuild images after dependency or base-image trust updates. Do not disable certificate verification to work around trust failures.
Scorecard findings describe repository practices; their count is not a count of exploitable vulnerabilities. Address technical findings in their owning code or workflow, rerun the analyzer on the default branch, and retain the resulting check evidence. Do not disable an analyzer or present a missing certification as a vulnerability fix.
| Signal | Repository evidence and handling |
|---|---|
| Automated tests | The maintained Python matrix and Windows/macOS lanes run on PRs and main. The primary lane enforces combined branch coverage; separate transport and recovery checks retain their own gates. See contributing. |
| Static analysis | CodeQL, Ruff, mypy, and Bandit run in CI. A successful scan job does not establish that every finding is resolved; verify findings on the default branch after merging. |
| Dependency updates | Weekly grouped Python, Actions, and container proposals remain subject to review and the full CI gates. Reapply accepted updates as maintainer-authored commits; do not merge bot branches or add bot coauthor trailers. |
| Disclosure policy | The root policy publishes supported versions, private reporting, and response expectations directly. |
| Release delivery | The release workflow checks main's CI before publication and uses trusted publishing, artifact hashes, SBOMs, and provenance. |
| OpenSSF Best Practices badge | No badge is claimed. A badge is a separate voluntary self-certification, not an automatic consequence of these controls. |
The OpenSSF passing criteria were reviewed on 2026-10-20. Public repository evidence supports the licensing, documentation, contribution, version control, test, static analysis, HTTPS delivery, and disclosure-process requirements. A full application additionally needs maintainer attestations, including secure-development knowledge and private vulnerability-response history. Source code and CI cannot establish those personal or private facts. Do not invent an application identifier, publish an unearned badge, or transfer GitHub credentials to a certification service to remove a dashboard warning.
Disposition (2026-10-20): accepted administrative finding. The missing external self-certification is documented against the evidence above; the technical security controls remain active. Revisit this decision when a maintainer supplies the required attestations and completes the application. This assessment does not claim that the project has completed or passed it.
Scorecard's CI/SAST history check has a verified false positive for
PR #211, recorded on 2026-10-20.
GitHub reports that merged PR's base, head, and merge commit as
6287b3e2c8f8aaab3dfb5b5472d34156b3504b2d, with zero PR commits. Its commit has
successful CI and CodeQL checks, but the GraphQL PR commits(last: 1) connection
is empty. Scorecard 5.6.0 caches checks from that connection and treats the
empty list as missing checks without consulting the commit's check runs.
Consequently it reports 12 of 13 PRs checked despite successful checks on all
13 heads. The affected CI-Tests and SAST alerts are false positives, not omitted
validation. Keep both workflows and required branch checks enabled; rerun
Scorecard after release and reassess if its underlying history changes.