securl 1.4.1

package/CHANGELOG.md

@@ -0,0 +1,241 @@
+# Changelog
+
+All notable changes to `securl` will be documented in this file.
+
+The format is based on Keep a Changelog and this package follows Semantic Versioning once published.
+
+## [Unreleased]
+
+## [1.4.1] - 2026-06-14
+
+### Changed
+- Refreshed package metadata and trust documentation after moving the source repository to `this-is-securl/securl`.
+
+## [1.4.0] - 2026-06-13
+
+### Added
+- Added structured finding evidence references and a remediation plan builder for prioritized, owner-aware fix guidance.
+- Added the `securl/remediation-plan` package export for clients that want to build fix plans from scan results.
+
+## [1.3.0] - 2026-06-11
+
+### Added
+- Added posture drift reports that combine history diffs, risk events, severity counts, changed areas, and overall drift direction into one stable monitoring payload.
+- Added the `securl/posture-drift` package export for clients building history, monitoring, or alerting workflows.
+
+## [1.2.1] - 2026-06-06
+
+### Changed
+- Capped A-level posture grades when Domain & Trust is weak, so strong browser-facing headers no longer mask broad DNS, email, or public-trust gaps in quiet or standard scans.
+
+## [1.2.0] - 2026-06-04
+
+### Added
+- Added `buildPostureDigest()` for producing compact, API/mobile-friendly summaries from full scan results.
+- Added the `securl/posture-digest` package export for consumers that want the digest helper without importing the wider SDK surface.
+
+## [1.1.1] - 2026-06-02
+
+### Changed
+- Refreshed npm package signalling with clearer CLI, CI, SDK, and monitoring examples for developer adoption.
+- Expanded package keywords and shipped examples to make the engine easier to discover for posture, CI, and vendor-risk workflows.
+
+## [1.1.0] - 2026-06-01
+
+### Added
+- Added posture risk event classification helpers for scan history diffs, including score, grade, certificate, security-header, WAF, CT-host, third-party, AI-vendor, identity-provider, and new critical-finding changes.
+- Added the `securl/risk-events` package export for consumers that want to build monitoring or alerting workflows from scan comparisons.
+
+### Changed
+- Added `currentGrade` to `HistoryDiff` so consumers can render grade movement without carrying a separate current snapshot.
+
+## [1.0.1] - 2026-05-30
+
+### Added
+- Added passive public IOC and abuse indicators, including off-origin credential-form review signals, suspicious script markers, CT takeover evidence, exposure findings, and visible client-library advisory matches.
+
+## [1.0.0] - 2026-05-27
+
+### Added
+- Added score driver metadata to analysis results so callers can explain the largest score deductions and limited-assessment caps.
+- Added deterministic scoring calibration profiles and passive signature registry tests to protect launch-facing grade expectations.
+- Added `deep-passive` scan mode for broader bounded CT sampling, crawl, exposure, and API-surface checks.
+
+### Changed
+- Documented default, quiet, and deep-passive scan boundaries and CI policy modes more explicitly in CLI help and the package README.
+- Hardened public-target validation coverage for normalized private IP literal forms, including IPv6-mapped loopback redirects.
+
+## [0.11.2] - 2026-05-24
+
+### Changed
+- Replaced Cheerio with `node-html-parser` for passive HTML page analysis, reducing the core package dependency tree while preserving title, metadata, form, script, stylesheet, link, and SRI extraction behavior.
+
+## [0.11.1] - 2026-05-21
+
+### Changed
+- Refreshed the npm package README and package metadata with clearer SecURL product positioning, hosted scanner links, and marketing site links.
+
+## [0.11.0] - 2026-05-20
+
+### Added
+- Added redirect-chain analysis from the existing fetch flow, including mixed HTTP hops, long chains, and cross-domain final destination flags.
+- Added aggregate cookie attribute analysis for `Secure`, `HttpOnly`, `SameSite`, session-cookie, `__Host-`, and `__Secure-` signals.
+- Added DKIM common-selector discovery, deeper SPF mechanism analysis, and an email deliverability composite score.
+- Added RFC 9116-oriented `security.txt` validation with valid, expired, incomplete, and missing states.
+- Added Subresource Integrity coverage scoring for externally hosted scripts and stylesheets.
+- Added passive framework/version leakage signals for common frontend frameworks and CMS markers found in fetched HTML.
+- Added protocol and WAF summary fields to passive infrastructure analysis using response headers such as `Alt-Svc`, `cf-ray`, `x-iinfo`, and related edge signatures.
+
+## [0.10.0] - 2026-05-19
+
+### Added
+- Added TLS-RPT DNS record detection to domain security analysis. Reports `_smtp._tls` records, flags missing TLS-RPT when MTA-STS is present, and exposes `tlsRpt` on the public `DomainSecurityInfo` type.
+- Added BIMI DNS record detection (`default._bimi`) to domain security analysis, including detection of the BIMI `v=BIMI1` indicator and `bimi` on the public `DomainSecurityInfo` type.
+- Added infrastructure provider detection for Bunny.net (CDN), Cloudflare Pages, Railway, Render, Fly.io, Hostinger, OVHcloud, and Hetzner.
+- Added analytics and session-replay vendor detection for Plausible, Matomo, Segment, Mixpanel, Amplitude, Heap, Microsoft Clarity, LogRocket, Pendo, New Relic Browser, and Datadog RUM.
+- Promoted analytics/telemetry and session-replay/experience-analytics to explicit third-party risk categories in HTML passive analysis.
+
+## [0.9.0] - 2026-05-17
+
+### Added
+- Added `passiveIntelligence` to the public analysis result model, summarizing passive stack, infrastructure, telemetry, third-party, AI, trust, email, and exposure signals.
+- Added a strict passive-collection boundary statement so downstream consumers can distinguish public-response intelligence from aggressive reconnaissance.
+- Added deterministic core coverage for passive intelligence summaries and boundary wording.
+
+### Changed
+- Exposed passive intelligence through hosted scan evidence payloads for API clients and future report/export consumers.
+
+## [0.8.2] - 2026-05-14
+
+### Added
+- Added optional scan timing metadata for total, core, and enrichment phases so callers can understand slow or partial scans.
+- Added a configurable maximum scan duration option for callers that need bounded execution.
+
+### Changed
+- Bounded secondary enrichment so long-running scans return a partial timed-out posture result instead of hanging indefinitely.
+- Tightened network and runtime safety around redirects, request failures, memory usage, and Node.js runtime support.
+- Refined passive DNS, certificate-transparency, and secondary probe handling to reduce latency spikes while preserving useful evidence.
+
+## [0.8.1] - 2026-05-07
+
+### Changed
+- Refined posture scoring so hosted-platform app URLs take a softer domain-trust penalty when the target is clearly a demo or PaaS-hosted surface rather than an owned apex domain.
+- Recalibrated `AI & Automation` posture scoring so absent visible AI surface is treated as low exposure rather than perfect assurance.
+- Improved surface-enrichment handling for SPA frontend fallbacks so successful responses on paths like `/.git/HEAD` or `/.env` are no longer misreported as exposed sensitive files when they clearly return the standard app shell.
+- Simplified and modularized the core scan pipeline internals so scoring, enrichment, and summary assembly are easier to evolve without changing the public API.
+- Expanded deterministic coverage for scoring calibration and frontend-fallback exposure detection.
+
+## [0.8.0] - 2026-04-29
+
+### Added
+- Added structured limited-read handling for blocked, timeout, and TLS-validation failures so constrained scans return an explicit `U` posture result instead of crashing or overclaiming confidence.
+- Added passive training or challenge-surface narrative detection so lab-style targets are called out in executive summaries without polluting posture scoring.
+- Added `Client code signals` to summarize framework, vendor, API/config, and version-hint intelligence from visible client-side assets.
+
+### Changed
+- Recalibrated posture scoring again so weak public targets spread more honestly across grades, with stronger penalties for missing browser-layer controls and breadth-of-weakness across categories.
+- Tightened executive summary wording so browser hardening, transport/access limits, and constrained reads drive the main visible risk more consistently.
+- Cleaned certificate-transparency fallback messaging so unreadable public-source responses produce calm narrative output instead of raw parser errors.
+- Improved exposure and API probe handling so repeated server-side errors on sensitive or API-style paths are surfaced as review-worthy signals.
+- Hardened the server boundary by making `/api/analyze` `GET`-only, returning minimal `/api/health` output in production, and degrading distributed rate limiting into a safer local fallback.
+- Expanded deterministic coverage for scoring, CT fallback, and server hardening behavior.
+
+## [0.7.0] - 2026-04-25
+
+### Added
+- Added the short `epi` CLI binary alias alongside `external-posture-insight`.
+- Added lightweight interactive multi-target CLI progress on stderr while keeping stdout report output pipe-friendly.
+- Added structured SPF and DMARC policy evaluation to `DomainSecurityInfo`, including SPF all-mechanism strength, DNS lookup-mechanism count, DMARC enforcement policy, rollout percentage, and reporting presence.
+- Added `analyzeInfrastructure()` for passive cloud/CDN/edge/hosting inference from DNS, reverse DNS, headers, and detected technology evidence.
+- Added `InfrastructureInfo` and related provider signal types to the public result model.
+- Added deterministic core test coverage for infrastructure provider inference.
+- Added quiet scan mode via `analyzeUrl(target, { scanMode: "quiet" })` and CLI `--quiet`.
+
+### Changed
+- Treat HTTP 5xx target responses as limited availability reads and cap their posture grade below `C` so unavailable pages do not look like normal mixed posture results.
+- Recalibrated `analyzeUrl()` scoring around weighted posture areas so the overall grade reflects domain/trust, exposure, API, third-party, and AI posture alongside core hardening controls.
+- Added bounded concurrency for CT host sampling, OSV vulnerability detail lookups, and related-page crawl checks.
+- Lazy-loaded Cheerio inside HTML analysis so importing the package is fast for CLI/help and workflows that do not parse page HTML.
+- Clarified README safety wording, CLI quick-start examples, and package usage boundaries for public launch.
+
+## [0.6.1] - 2026-04-19
+
+### Changed
+- Refreshed direct and transitive dependencies via Dependabot group update, including `react-router-dom` and multiple security-relevant parser/glob stack updates (`js-yaml`, `picomatch`, `brace-expansion`, `minimatch`, `glob`, `flatted`).
+- Verified package build and test flows continue to pass after lockfile refresh.
+
+## [0.6.0] - 2026-04-16
+
+### Added
+- CLI policy gating with `--fail-on info|warning|critical` for CI exit-code control.
+- CLI regression policy mode with `--fail-on-regression` for baseline/compare workflows.
+- Compact `ci-json` CLI output for scan/compare automation pipelines.
+- CLI score-threshold gating with `--fail-if-score-below <0-100>`.
+- Richer batch scan summaries in summary/Markdown output with aggregate score and strongest/weakest targets.
+
+### Changed
+- Updated Vite toolchain compatibility to keep installs stable with current plugin peer dependencies.
+- Hardened TLS certificate issuer/subject normalization for stricter TypeScript handling.
+- Expanded CLI tests and help-surface assertions for policy mode usage.
+
+## [0.5.0] - 2026-04-16
+
+### Added
+- CLI batch scanning via `scan <target...>` with summary, Markdown table, and JSON output support.
+- CLI report-to-report comparison via `compare <current-report.json> <baseline-report.json>`.
+- CLI SARIF output for both scans and comparisons, including compare mode output focused on newly introduced findings.
+- Core CLI test coverage for comparison workflows, JSON/SARIF output, malformed baseline handling, and invalid baseline usage in multi-target scans.
+
+### Changed
+- Expanded CLI help and package README examples/documentation to cover batch scans, direct comparisons, and SARIF output.
+- Improved CLI argument parsing to support command-oriented workflows while keeping baseline comparisons scoped to single-target scans.
+
+## [0.4.0] - 2026-04-09
+
+### Added
+- Passive library risk detection from explicitly versioned script URLs with OSV-backed advisory lookups.
+- Score trending in the monitoring UI and a shared history-diff model exported from the core package.
+- CLI baseline comparison support via `--baseline <report.json>`.
+- Passive DNSSEC posture and certificate-transparency takeover clues from sampled CNAME evidence.
+
+### Changed
+- Hardened scan dispatch with stricter public-target revalidation on outbound requests.
+- Added explicit timeout handling around OIDC discovery and improved hosted-mode server boundary controls.
+- Versioned browser-local monitoring storage and surfaced clearer target-cap feedback in the app.
+- Unified app and package diff logic so monitoring and CLI comparisons use the same change model.
+
+## [0.3.0] - 2026-04-08
+
+### Added
+- A first-class CLI entrypoint with `scan`, summary/JSON/Markdown output, and file output support.
+- Richer monitoring diffs covering certificate windows, third-party providers, AI vendors, identity-provider changes, WAF changes, and CT priority-host changes.
+- WAF and edge fingerprinting with passive provider inference.
+- Certificate Transparency coverage rollups with prioritized and sampled hosts.
+
+### Changed
+- Deepened passive identity discovery with stronger OAuth/OIDC heuristics and less eager same-origin redirect attribution.
+- Improved passive-signal messaging and UI consistency for identity, CT, third-party trust, and disclosure/domain trust panels.
+- Consolidated duplicated core helpers and documented scanner limits in shared config.
+
+## [0.2.0] - 2026-04-07
+
+### Added
+- Passive Identity Provider and OAuth discovery, including public OpenID configuration checks.
+- Certificate Transparency discovery with bounded, best-effort lookup behavior.
+- Staged strict TypeScript verification for extracted core modules.
+- Dependabot configuration and npm publish provenance support for release hygiene.
+
+### Changed
+- Replaced regex-driven HTML parsing with a Cheerio-based DOM inspection path.
+- Extracted CT, identity, HTML insight, and surface-enrichment logic out of the core scanner monolith.
+- Hardened the local server boundary with request validation, basic rate limiting, and safer API error responses.
+- Added package `engines` metadata and simplified the repo to a single npm lockfile story.
+
+## [0.1.0] - 2026-04-05
+
+### Added
+- Initial extracted scanner core package.
+- Passive HTML/client exposure analysis.
+- AI surface, third-party trust, DNS/mail posture, exposure, and API-surface analysis.
+- OWASP/MITRE-aligned finding labeling.
+- Regression fixtures for known false positives.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keith Batterham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,427 @@
+# securl
+
+[![npm version](https://img.shields.io/npm/v/securl)](https://www.npmjs.com/package/securl)
+[![npm package](https://img.shields.io/badge/npm-package-red)](https://www.npmjs.com/package/securl)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![SecURL package checks](https://github.com/this-is-securl/securl/actions/workflows/core-package-checks.yml/badge.svg)](https://github.com/this-is-securl/securl/actions/workflows/core-package-checks.yml)
+
+**The passive security posture engine behind SecURL.**
+
+`securl` 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
+
+<p>
+  <a href="https://securl.online"><strong>Visit the SecURL site</strong></a>
+  ·
+  <a href="https://app.securl.online"><strong>Try the live scanner</strong></a>
+  ·
+  <a href="https://apps.apple.com/app/securl/id6774322464"><strong>Get the iOS app</strong></a>
+  ·
+  <a href="https://github.com/this-is-securl/securl"><strong>View the source</strong></a>
+</p>
+
+## Quick Start
+
+Run a scan without installing:
+
+```bash
+npx securl scan example.com
+```
+
+Install globally for the `securl` command:
+
+```bash
+npm install -g securl
+securl 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 securl 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 securl 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 securl scan https://example.com \
+  --baseline ./security-baseline.json \
+  --fail-on-regression
+```
+
+### 3. Node.js SDK scan
+
+```js
+import { analyzeUrl } from "securl";
+
+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 "securl/history-diff";
+import {
+  buildPostureRiskEventsFromSnapshots,
+} from "securl/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 "securl/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 "securl";
+import { buildPostureDigest } from "securl/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 "securl/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
+
+SecURL 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:
+
+- [`securl`](https://www.npmjs.com/package/securl)
+- 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 SecURL 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 `securl-v1.4.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:
+
+- `securl/history-diff`
+- `securl/posture-digest`
+- `securl/posture-drift`
+- `securl/remediation-plan`
+- `securl/risk-events`
+- `securl/types`
+
+## CLI
+
+The package includes a pipe-friendly CLI:
+
+Scan multiple targets in one run:
+
+```bash
+npx securl scan example.com github.com bbc.co.uk
+securl scan example.com github.com bbc.co.uk
+```
+
+Available output formats:
+
+```bash
+npx securl scan example.com --format summary
+npx securl scan example.com --format json
+npx securl scan example.com --format markdown
+npx securl scan example.com --format sarif
+npx securl 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 securl scan example.com
+npx securl scan example.com --quiet
+npx securl 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 securl scan example.com github.com --fail-on warning
+npx securl scan example.com --baseline previous-report.json --fail-on-regression
+npx securl scan example.com github.com --fail-if-score-below 75
+npx securl 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 securl scan example.com --format json --output report.json
+```
+
+Compare against a previously saved JSON report:
+
+```bash
+npx securl scan example.com --baseline previous-report.json
+```
+
+Compare two saved reports directly:
+
+```bash
+npx securl compare current-report.json baseline-report.json
+npx securl 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 securl --help
+```
+
+### `analyzeUrl(url)`
+
+Run a full posture analysis for a public target.
+
+```js
+import { analyzeUrl } from "securl";
+
+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 "securl";
+
+const htmlSecurity = analyzeHtmlDocument("https://example.com", "<html>...</html>");
+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.