Periscan

Prove authorized exposures are real — and only mark them Fixed when a retest says so.

Keep proving: authorized local path → Gitleaks-class → Fixed after retest.

Community edition is the Apache-2.0 validation slice: authorized local clone, policy, Gitleaks-class secrets (jobsQueued=1), evidence. Fixed only after a retest. Full BAS/AEV is the development objective; this Community start is the current shipped entry point. Not a Wiz / Tenable replacement. Not a live exploit library.

For: AppSec, platform, and security engineers who own the target, or are contracted to test it.

Not for: unauthorized scanning. BAS/AEV development includes Atomic, Caldera, SharpHound/BloodHound and Metasploit; live adapters require the qualification gates in the program.

Need Node 24 (.nvmrc) and Docker. pnpm 9.15.0 via Corepack.

Community · FAQ · Using · Setup · Security · Settled

Keep proving: authorize a local clone → Gitleaks-class secrets finding with evidence → remediate → retest. Fixed only after the retest clears it. Schedule the next run.

Start

Clone this repo, inspect it, then install. Node 24 and Docker first.

git clone https://github.com/seanventures/periscan.git
cd periscan
bash scripts/periscan.sh install
bash scripts/periscan.sh start

Then in the UI — one job:

1. Authorize a local clone path — git clone <your-repo> on the machine running Periscan, then paste the absolute path. A hosted github.com/org/repo URL is not a control-plane path. (The UI refuses the URL and shows the clone command — paste the path after clone.)
2. Run Community validation — default start is Gitleaks-class secrets (jobsQueued=1). Not the full pack. Not the engine mall below. Keep the board running.
3. Open remediations from that mission. They stay Open until a retest produces a verification event. Creating a ticket is not Fixed.

Secondary one-paste (inspect install.sh first):

curl -fsSL --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/seanventures/periscan/main/install.sh | bash

Safer: download, inspect, then bash install.sh. bash install.sh --dry-run prints the plan. Pipe help: bash -s -- --help.

Repair:

bash install.sh doctor    # health + repair
bash install.sh health    # check only
bash install.sh --dry-run

Local/self-host: docs/SETUP.md. Operator notes: USING.md. Full FAQ: docs/FAQ.md. Offering: COMMUNITY.md.

Measurement mark lives in docs/BADGES.md. This repo has no dogfood Community evidence yet — do not treat the product as measured.

Contents

• Start
• Docs
• Proof loop
• Safety floor
• Compared to
• Community pack
• Contributing
• License

---

Proof loop

flowchart LR
  A[Authorize scope] --> B{Policy}
  B -->|Denied| C[Never queued]
  B -->|Allow| D[Community pack]
  D --> E[Evidence]
  E --> F[Findings]
  F --> G[Remediate]
  G --> H[Retest]
  H -->|Still exposed| F
  H -->|Measured clear| I[Fixed]

Loading

Scope	How you prove authorization
Domain / subdomain	DNS TXT
Repository	.periscan-authorization token file (or Owner/Admin attestation when runner-only)
Cloud account	Connected AWS account match, or Owner/Admin attestation
IP range / internal net	Audited Owner/Admin attestation

Denied work never queues. No evidence for that mission → empty list, not theater. Fixed requires a verification event; ticket close is ClosedWithoutEvidence.

---

Safety floor

This is the product, not a missing checkbox.

Guarantee	Meaning
Authorized scope only	No third-party scanning without verified authorization
Denied never queued	Policy Denied fails closed before the job queue
Non-destructive	No exfil, persistence, credential theft, or uncontrolled exploit chaining
Live offensive packs off	Unqualified adapters stay off until implementation, policy, cleanup and evidence gates pass
Runner is outbound	HTTPS signed-task polling. No inbound management plane as the default
Fixed is earned	Status Fixed only after a measured retest
Path words are earned	validated / measured / reachable / exploitable follow weakest-hop evidence
Scanners stay backstage	Tool JSON is evidence, not the UX or the report

SECURITY_BOUNDARIES.md · SECURITY.md · docs/SETTLED.md

---

Compared to what you already run

Community start is Gitleaks-class secrets (jobsQueued=1) on an authorized local clone. Keep proving: review, re-verify, schedule the next run. The broader program is BAS/AEV plus authorized validation — not an ASV/CTEM platform in a box, and not a live exploit library.

	CLI scanners	Aggregators (DefectDojo)	CNAPP / RBVM	BAS / auto-pentest	Periscan
Job	Find issues	Dedup imports	Inventory / vuln SoR	Attack libraries	Prove exposure and re-prove fixes
Starts without verified scope?	Usually	N/A	Connectors	Often	No
Policy deny never queues?	Exit codes	N/A	Tickets	Varies	Product guarantee
Fixed	Re-run the tool	Ticket workflow	SLA / close	Sometimes retest	Only after verification
Live ransomware / kill-chain	Unrelated	Unrelated	Unrelated	Often the demo	Hard no
Replace Wiz / Tenable?	No	No	They are those	No	No — co-exist
Product LICENSE	Usually Apache/MIT	BSD (DefectDojo OS)	Proprietary	Proprietary	Apache-2.0 + upstream engine SPDX

Nuclei is a first-class engine (second mission, allowlisted safe profiles). Periscan is not a Nuclei wrapper and does not compete on template count.

---

Community pack

Self-hosted validation slice: verified scope + policy + permissive SPDX engines + first-party checks + evidence. Load binaries in Engine Lab → Install + enable Community pack.

Default start on a verified repo is Gitleaks-class secrets (jobsQueued=1). The table below is the installable catalog — a second control, not the start button. BAS adapters (Atomic / Caldera / SharpHound / Metasploit) need qualification; this is not a live exploit library.

Not live Atomic / Caldera / Metasploit / sqlmap. Source is Apache-2.0; third-party engines keep their own SPDX.

Pack	Installable catalog (not the default start)
Secrets	Gitleaks, detect-secrets, git-secrets, secretlint, Talisman, Whispers
SCA	Trivy, OSV-Scanner, Grype, pip-audit, govulncheck, cargo-audit, retire.js, Nancy, Dependency-Check
SAST	Bandit, gosec, Brakeman, Horusec, Sobelow
IaC	Checkov, Terrascan, KICS, kube-linter, kube-score, Kubescape, Conftest, tfsec, cfn-nag, Polaris, kubeaudit, Trivy misconfig
SBOM / provenance	Syft, cdxgen, slsa-verifier
Containers / Kubernetes	Dockle, Trivy, kube-bench, Popeye
TLS / HTTP	SSLyze, tlsx, first-party DNS / headers / cookies / CORS
Web	ZAP baseline, Katana; Nuclei safe exposure (second mission)
Cloud	Prowler on Connected AWS, cloudlist
Recon (runner enrolled)	nmap, naabu, Amass passive, Subfinder, httpx, dnsx
Detection content	YARA repo rules, Falco rules lint (not Falco-as-runtime)

GPL / LGPL (Semgrep, testssl, Nikto, …) stay Engine Lab + license accept. Atomic / Caldera / SharpHound / Metasploit are BAS development targets; current unqualified adapters remain excluded from Community start. sqlmap remains unavailable for live validation.

Missing binaries are tool_unavailable / Inconclusive — not invented findings.

---

Contributing

Apache-2.0 with an open-source engine-adapter surface. Read CONTRIBUTING.md, docs/ADAPTER_FIRST_PR.md, and GOVERNANCE.md.

File issues on seanventures/periscan (bug, feature, engine-adapter).

Rung	What to send	Done looks like
0. Hygiene	Typo, claim-language nit	Matches the claim deny-list
1. First useful PR	Module adapter + fixture for a permissive engine (cfn-lint, tflint, parliament)	pnpm --filter @periscan/modules test, pnpm licenses:check
2. Pack honesty	License row, Engine Lab metadata, notices	pnpm licenses:write then pnpm licenses:check
3. Policy / Fixed	Denied never queues, or Fixed cannot flip without verify	Hits policy / fix-verification tests
4. Intake (no binary)	POST /api/v1/third-party-tools/intake/validate	Certification report; not an unreviewed runtime
5. Change control	Prisma wholesale, runner transport, LICENSE	Existing approval rules apply. BAS development follows the authorized program and adapter release gates.

Build and qualify BAS/AEV adapters under the authorized program. Preserve auth, outbound signed-task transport and evidence-focused UX. Customer execution requires a qualified scenario and its scope-bound policy decision.

Verify

pnpm verify

That is the release gate. Before a PR: pnpm lint && pnpm typecheck && pnpm test && pnpm licenses:check.

---

License

Root LICENSE is Apache-2.0. Community edition is the open-core validation slice, not a second product license. Full BAS/AEV expansion follows the program. Hosted SaaS / MSSP / marketplace stay commercial product. Third-party engines keep their SPDX — licenses/THIRD_PARTY_NOTICES.md. The private product tree stays private.

OPEN_CORE.md · NOTICE

---

Docs

Doc	What it covers
SETUP	Prerequisites, install, local path, Gitleaks-class start, Fixed-via-verify
FAQ	Short claim-safe answers
USING	Ports, HTTP proof loop, lab hops
SECURITY	Vulnerability intake (title-only [SECURITY], no PoC)
COMMUNITY	What Community edition is / is not
OPEN_CORE	Apache-2.0 slice vs commercial surface
docs/ENTERPRISE.md	CISO / admin: Community vs commercial
docs/SOC2.md	Vendor Type II not claimed; customer support pack
docs/SETTLED.md	Settled axioms
ARCHITECTURE.md	System shape
CODE_OF_CONDUCT.md	Conduct

More

See Docs. docs/FAQ.md · docs/USING.md

Maintainer: GitHub has no API for the social preview image — upload docs/images/github-social-preview.png (1280×640) at Settings → Social preview.