# @ktbatterham/external-posture-core [![npm version](https://img.shields.io/npm/v/%40ktbatterham%2Fexternal-posture-core)](https://www.npmjs.com/package/@ktbatterham/external-posture-core) [![npm package](https://img.shields.io/badge/npm-package-red)](https://www.npmjs.com/package/@ktbatterham/external-posture-core) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) [![Core package checks](https://github.com/ktbatterham/external-posture-insight/actions/workflows/core-package-checks.yml/badge.svg)](https://github.com/ktbatterham/external-posture-insight/actions/workflows/core-package-checks.yml) **The passive security posture engine behind SecURL.** `@ktbatterham/external-posture-core` is the reusable scanner engine behind [SecURL](https://securl.online), a posture-first external security review tool for public web targets. It is designed for passive, low-noise assessment rather than active exploitation or broad reconnaissance. The engine turns public web signals into structured JSON, Markdown, SARIF, and CI-friendly output. Use it when you need a fast outside-in read on a public web service: - run a security posture smoke check in CI before release - generate JSON or SARIF evidence for internal review - compare the current posture against a saved baseline - classify monitoring changes into risk events for alerts or dashboards - enrich vendor, supplier, or customer domain reviews without credentials or agents

Visit the SecURL site · Try the live scanner · Get the iOS app · View the source

## Quick Start Run a scan without installing: ```bash npx @ktbatterham/external-posture-core scan example.com ``` Install globally for the short `epi` command: ```bash npm install -g @ktbatterham/external-posture-core epi scan example.com ``` Prefer the hosted report workspace? Use [app.securl.online](https://app.securl.online). For the product overview, start at [securl.online](https://securl.online). Prefer mobile? Install [SecURL on the App Store](https://apps.apple.com/app/securl/id6774322464). ## Common use cases ### 1. Quick CLI posture check ```bash npx @ktbatterham/external-posture-core scan https://example.com --format summary ``` Example summary output: ```text example.com A 93/100 2 findings ``` ### 2. CI gate for public-facing deployments Fail the job when a target drops below a minimum score or introduces warning-level findings: ```bash npx @ktbatterham/external-posture-core scan https://example.com \ --quiet \ --format ci-json \ --fail-if-score-below 75 \ --fail-on warning ``` Compare a new scan with a saved baseline: ```bash npx @ktbatterham/external-posture-core scan https://example.com \ --baseline ./security-baseline.json \ --fail-on-regression ``` ### 3. Node.js SDK scan ```js import { analyzeUrl } from "@ktbatterham/external-posture-core"; const result = await analyzeUrl("https://example.com", { scanMode: "quiet", }); console.log({ score: result.score, grade: result.grade, mainRisk: result.executiveSummary.mainRisk, findings: result.issues.map((issue) => ({ severity: issue.severity, title: issue.title, })), }); ``` ### 4. Monitoring and risk-event classification Version `1.1.0+` includes helpers for turning two scan snapshots into alert-friendly posture events. ```js import { buildHistoryDiffFromSnapshots, snapshotFromAnalysis, } from "@ktbatterham/external-posture-core/history-diff"; import { buildPostureRiskEventsFromSnapshots, } from "@ktbatterham/external-posture-core/risk-events"; const currentSnapshot = snapshotFromAnalysis(currentReport); const previousSnapshot = snapshotFromAnalysis(previousReport); const diff = buildHistoryDiffFromSnapshots(currentSnapshot, previousSnapshot); const riskEvents = buildPostureRiskEventsFromSnapshots( currentSnapshot, previousSnapshot, diff, ); console.log(riskEvents); ``` Risk events include score regressions, grade drops, new critical findings, certificates nearing expiry, security header regressions, WAF signal removals, new CT priority hosts, identity-provider changes, and new third-party or AI vendors. Version `1.3.0+` also includes a higher-level posture drift report for monitoring and alerting surfaces that need one stable payload with the diff, risk events, changed areas, severity counts, and an overall direction. ```js import { buildPostureDriftReportFromSnapshots, } from "@ktbatterham/external-posture-core/posture-drift"; const drift = buildPostureDriftReportFromSnapshots( currentSnapshot, previousSnapshot, ); console.log(drift.summary.direction, drift.summary.changedAreas); ``` Runnable examples are included in [`examples/`](./examples): ```bash node examples/scan-url.mjs https://example.com node examples/risk-events.mjs current-report.json previous-report.json ``` ### 5. Compact posture digest for APIs and mobile clients Version `1.2.0+` includes a digest helper for turning a full scan result into a smaller, stable summary payload. ```js import { analyzeUrl } from "@ktbatterham/external-posture-core"; import { buildPostureDigest } from "@ktbatterham/external-posture-core/posture-digest"; const result = await analyzeUrl("https://example.com", { scanMode: "quiet", }); const digest = buildPostureDigest(result); console.log({ grade: digest.posture.grade, score: digest.posture.score, topFindings: digest.findings.top, topFixes: digest.remediationPlan?.topActions, riskIndicators: digest.intelligence.riskIndicators, }); ``` ### 6. Evidence-backed remediation plans Version `1.4.0+` includes a remediation plan helper that turns score drivers and findings into prioritized, owner-aware fix guidance. Findings can also carry structured evidence references so clients can show why a finding was raised. ```js import { attachIssueEvidence, buildPostureRemediationPlan, } from "@ktbatterham/external-posture-core/remediation-plan"; const resultWithEvidence = attachIssueEvidence(result); const remediationPlan = buildPostureRemediationPlan(resultWithEvidence); console.log(remediationPlan.items.map((item) => ({ title: item.title, owner: item.owner, impact: item.impact, action: item.action, }))); ``` ## Package trust and release signals - public source repository with package code under `packages/core` - npm publishing from GitHub Actions with provenance enabled - CI checks covering audit, build, lint, tests, and dry-run packaging - no install scripts - one runtime dependency (`node-html-parser`) - published MIT license, changelog, release notes, and security policy Security disclosure guidance: - [`packages/core/SECURITY.md`](./SECURITY.md) - [`/SECURITY.md`](../../SECURITY.md) ## Safety model External Posture Insight is passive-first and production-conscious, but it is not magic invisibility dust. A standard scan may make DNS queries, perform TLS handshakes, fetch the target page, follow redirects, query third-party public datasets such as Certificate Transparency / OSV, and run a small set of low-noise HTTP checks. It does not attempt exploitation, brute forcing, authentication bypass, form submission, fuzzing, password testing, or vulnerability exploitation. Use it only against systems you own or are authorized to assess. Results are heuristic and should be treated as decision support, not a formal penetration test or compliance attestation. ## What it covers - HTTP security headers and redirect posture - TLS and certificate inspection - Cookie hygiene - Passive HTML inspection - Passive public IOC and abuse indicators for suspicious scripts, off-origin credential flows, exposed paths, CT takeover clues, and visible vulnerable client libraries - AI surface and third-party trust signals - Low-noise exposure, CORS, API-surface, and DNS/mail posture checks - OWASP/MITRE-aligned finding labels ## Current status This package is published and consumable from npm: - [`@ktbatterham/external-posture-core`](https://www.npmjs.com/package/@ktbatterham/external-posture-core) - Product site: [securl.online](https://securl.online) - Live scanner: [app.securl.online](https://app.securl.online) - iOS app: [SecURL on the App Store](https://apps.apple.com/app/securl/id6774322464) It is also used by the External Posture Insight app from the local workspace during development. ## Release workflow - local package check: `npm run pack:core` - CI verification: `.github/workflows/core-package-checks.yml` - publish workflow: `.github/workflows/publish-core-package.yml` - publish requires an `NPM_TOKEN` repository secret - publish uses npm provenance (`npm publish --provenance`) Recommended release flow: 1. update the version in `packages/core/package.json` 2. run `npm run test:core` 3. run `npm run pack:core` 4. create and push a tag like `core-v0.1.1` 5. let the publish workflow release the package See also: - `packages/core/CHANGELOG.md` - `packages/core/RELEASING.md` ## Public API Primary exports: - `analyzeUrl(url, options)` - scan a public target and return a structured posture result. - `analyzeTarget(url, options)` - compatibility alias for `analyzeUrl`. - `analyzeHtmlDocument(url, html)` - run passive HTML/content analysis against already-fetched markup. - `snapshotFromAnalysis(result)` - reduce a scan result to a comparison snapshot. - `buildHistoryDiffFromSnapshots(current, previous)` - build a structured diff between scans. - `buildPostureRiskEventsFromSnapshots(current, previous, diff)` - classify scan changes into alert-friendly risk events. - `buildPostureDigest(result)` - reduce a full scan result to a compact API/mobile-friendly digest. - `buildPostureDriftReportFromSnapshots(current, previous)` - produce a complete scan-to-scan drift report for monitoring, alerting, and history views. - `buildPostureRemediationPlan(result)` - generate prioritized, owner-aware remediation actions from findings and score drivers. - `attachIssueEvidence(result)` - add structured evidence references to findings without changing their existing fields. Package subpath exports: - `@ktbatterham/external-posture-core/history-diff` - `@ktbatterham/external-posture-core/posture-digest` - `@ktbatterham/external-posture-core/posture-drift` - `@ktbatterham/external-posture-core/remediation-plan` - `@ktbatterham/external-posture-core/risk-events` - `@ktbatterham/external-posture-core/types` ## CLI The package includes a pipe-friendly CLI: Scan multiple targets in one run: ```bash npx @ktbatterham/external-posture-core scan example.com github.com bbc.co.uk epi scan example.com github.com bbc.co.uk ``` Available output formats: ```bash npx @ktbatterham/external-posture-core scan example.com --format summary npx @ktbatterham/external-posture-core scan example.com --format json npx @ktbatterham/external-posture-core scan example.com --format markdown npx @ktbatterham/external-posture-core scan example.com --format sarif npx @ktbatterham/external-posture-core scan example.com --format ci-json ``` The CLI writes machine-readable report output to stdout, and lightweight multi-target progress to stderr only when running interactively. This keeps JSON/SARIF output pipe-friendly. Scan modes: ```bash npx @ktbatterham/external-posture-core scan example.com npx @ktbatterham/external-posture-core scan example.com --quiet npx @ktbatterham/external-posture-core scan example.com --deep-passive ``` - default scan: primary response plus bounded passive enrichment, including HTML, DNS/mail, Certificate Transparency, OSV, exposure, CORS, API-surface, and public trust signals. - `--quiet`: keeps primary response, TLS, headers, cookies, redirects, DNS/mail, Certificate Transparency summary, infrastructure, and public trust checks; skips page-body analysis, related-page crawl, security.txt fetch, identity discovery, exposure probes, CORS probes, API probes, OSV lookups, and CT host sampling. Use this for lower-noise CI smoke checks or frequent regression monitoring. - `--deep-passive`: expands passive CT host sampling, related-page crawl, exposure probes, and API-surface probes while keeping request counts and scan duration bounded. Use this for pre-release or scheduled posture reviews where a broader passive pass is worth the extra time. CI policy modes: ```bash npx @ktbatterham/external-posture-core scan example.com github.com --fail-on warning npx @ktbatterham/external-posture-core scan example.com --baseline previous-report.json --fail-on-regression npx @ktbatterham/external-posture-core scan example.com github.com --fail-if-score-below 75 npx @ktbatterham/external-posture-core compare current-report.json baseline-report.json --fail-on critical --fail-on-regression ``` - `--fail-on` sets exit code `1` when findings at or above the selected severity are present. - `--fail-on-regression` sets exit code `1` when the baseline comparison detects a regression (score drop, new issues, or worse HTTP status class). - `--fail-if-score-below` sets exit code `1` when any scanned target score is below the given threshold. Write results to a file: ```bash npx @ktbatterham/external-posture-core scan example.com --format json --output report.json ``` Compare against a previously saved JSON report: ```bash npx @ktbatterham/external-posture-core scan example.com --baseline previous-report.json ``` Compare two saved reports directly: ```bash npx @ktbatterham/external-posture-core compare current-report.json baseline-report.json npx @ktbatterham/external-posture-core compare current-report.json baseline-report.json --format sarif ``` Batch scans return: - summary: one line per target - markdown: a compact comparison table - sarif: one SARIF log containing findings across all scanned targets - ci-json: compact machine-readable output with policy pass/fail status - json: ```json { "analyses": [{ "...": "scan result" }] } ``` Direct report comparison returns: - summary: score, status, and change summary - markdown: a compact comparison report - sarif: only findings that are newly introduced in the current report versus the baseline - ci-json: compact machine-readable output with policy pass/fail status and diff details - json: ```json { "current": { "...": "latest saved report" }, "baseline": { "...": "older saved report" }, "diff": { "...": "structured change summary" } } ``` Show usage: ```bash npx @ktbatterham/external-posture-core --help ``` ### `analyzeUrl(url)` Run a full posture analysis for a public target. ```js import { analyzeUrl } from "@ktbatterham/external-posture-core"; const result = await analyzeUrl("https://example.com"); console.log(result.score, result.grade); ``` `analyzeTarget` remains available as a compatibility alias, but `analyzeUrl` is the primary public entrypoint. `analyzeUrl("https://example.com", { scanMode: "quiet" })` uses the same quiet boundary as CLI `--quiet`. `analyzeUrl("https://example.com", { scanMode: "deep-passive" })` uses the expanded passive recon boundary as CLI `--deep-passive`. When a baseline report is supplied to the CLI, summary and Markdown output append a `Changes Since Baseline` section. JSON output returns: ```json { "analysis": { "...": "latest scan result" }, "diff": { "...": "structured change summary" } } ``` ### `analyzeHtmlDocument(url, html)` Run passive HTML/content analysis against a fetched HTML document. ```js import { analyzeHtmlDocument } from "@ktbatterham/external-posture-core"; const htmlSecurity = analyzeHtmlDocument("https://example.com", "..."); console.log(htmlSecurity.clientExposureSignals); ``` ## Notes - Only use this against targets you are authorized to assess. - The package is intentionally conservative about active probing. - Default scans perform bounded passive enrichment; quiet scans skip page-body and probe-heavy enrichment to keep request volume lower. - Scoring is heuristic and should be treated as a prioritization aid, not an absolute security truth. - The author is not responsible for misuse, unauthorized scanning, operational impact, or decisions made from the output without appropriate validation.