Certusby Octave-X

A product of Octave-X Inc.

Restricted distributionSigned evidenceMerge gateOctave-X product

Certus Documentation

Compliance software that stops bad merges.

Certus turns every pull request into a signed compliance decision. It scans the change, maps findings to controls, posts the result where engineers work, and blocks merges that fall below policy.

Framework registry

Policy mapping surface

Blueprints + scanners

Verification inputs

CLI + Dashboard

Signed evidence flow

Restricted Package

Built for controlled rollout

Access to <pilot-issued-package> is authorized per organization. Install paths, GitHub App credentials, and evidence keys stay inside each customer environment.

Certus is a product of Octave-X Inc. The docs show the product surface, but repository sync, dashboard access, and registry credentials are enabled only for approved pilot workspaces.

Request pilot access Open approved workspace Review configuration

Why Certus

Shift compliance into the developer workflow.

Traditional compliance tools audit code after it ships. By then, the damage is done, non-compliant code is already in production, audit findings pile up, and remediation becomes a fire drill. Certus flips that. Protected PRs get a merge-gate status, signed evidence, and reviewer-ready findings before the merge button is available.

Traditional review	Certus
Audits run quarterly	Protected PRs are evaluated before merge
Findings surface weeks later	Findings surface in the PR comment
Evidence is collected manually	Evidence packs are signed and stored automatically
Developers learn about issues after shipping	Developers see exactly what to fix before merging
Compliance is a separate team problem	Compliance is part of the developer workflow

Table of Contents

Installation Pilot Runbook Your First Scan GitHub App Real Repo Example Command Reference Evidence Signing Scanners SDK + Frameworks CLI Connection Configuration Requirements

Installation

Install the CLI first.

Certus is provisioned through a controlled pilot channel. Approved organizations receive a scoped registry or tarball, an org API key, and an allowlisted GitHub App installation path for selected repositories.

Pilot install command

bashCertus

# Private npm install
# Use the exact package identifier issued during pilot onboarding
npm install -g <pilot-issued-package>@2.2.2

# Delivered tarball alternative
npm install -g ./certus-ai-2.2.2.tgz

# Verify the installed CLI
certus --version
# Output: 2.2.2

# Check system health
certus doctor

Public docs intentionally use a placeholder package reference. Approved pilots receive the exact scoped package identifier, any required registry-auth step, and the org API key during onboarding. Without those credentials, the CLI can run local commands but cannot sync evidence into a Certus workspace or attach to selected repositories.

bashCertus

# Authenticate the CLI against an approved pilot workspace
certus login   --api-url https://www.getcertus.cloud   --api-key <org-api-key>   --org <org-slug>

# Confirm dashboard sync, org, plan, and CLI version
certus status

What you are installing

Pilot-issued package reference: <pilot-issued-package>
CLI version: 2.2.2
Distribution owner: Octave-X Inc.
Supported entrypoint: certus
Repository sync: pilot workspace required

Pilot Runbook

Use one operator flow for every pilot.

A working pilot needs one narrow merge lane, not a broad rollout. Issue one workspace, bind one GitHub installation path, require one status check, then prove the path on real pull requests.

Operator sequence

bashCertus

# 1. Install the pilot CLI package from npm
npm install -g <pilot-issued-package>@2.2.2

# 2. Bind the CLI to the issued workspace
certus login   --api-url https://www.getcertus.cloud   --api-key <org-api-key>   --org <org-slug>

certus status

# 3. Install the managed GitHub App from Dashboard -> Integrations -> GitHub
#    on the approved repository scope

# 4. Require certus/compliance in GitHub branch protection or a ruleset

# 5. Run one real PR through the lane and verify stored evidence
certus evidence list

Done when

Step	Success condition
Issue pilot workspace	Create one org boundary, one operator key, and one approved repo scope.
Connect GitHub	Install the managed Certus GitHub App on selected repositories only.
Set branch enforcement	Require certus/compliance on the branch that receives merges.
Run a passing and failing PR	Prove the merge gate blocks and clears on the same repo path.
Verify evidence	Confirm PR comment, status, and signed evidence pack are all present.

What Certus manages

Hosted GitHub App, webhook receiver, merge-gate evaluation, PR reporting, and evidence storage.

What the pilot operator manages

Workspace issuance, repo approval, branch protection requiring certus/compliance, and reviewer adoption.

Operator access control

Set PILOT_OPERATOR_EMAILS for the pilot workspace operators who can issue workspaces and review blocked PRs.

What to avoid

Do not widen repo scope or framework scope until one protected branch lane behaves predictably.

Your First Scan

Run one command and get a scored result plus evidence.

A single scan runs the scanner passes, executes blueprints, maps findings to controls, hashes the evidence pack, and optionally attaches a JWS signature when a signing key is configured.

1. Run the scan

bashCertus

certus scan expressjs/express --ai

textCertus

  CERTUS  ·  Merge-Gate Compliance
  v2.2.2  ·  getcertus.cloud

  Cloned expressjs/express (shallow, 2.1s)
  Running 5 scanner passes ................. done (4.8s)
  Running compliance blueprints ............ done (3.2s)
  Mapping to compliance controls ........... done (0.3s)
  Signing evidence pack (SHA-256) .......... done (0.1s)
  AI compliance assessment ................. done (2.4s)

2. Read the results

textCertus

  --- Scan Results --------------------------------

  Grade       B+  (84/100)
  Verdict     PASSED
  Duration    12.8s
  Total       12 findings
  Critical    0
  High        2
  Medium      6
  Low         4
  Controls    24/29 passed
  Blueprints  14/18 passed

  --- Policy Checks -------------------------------

  Advisory  Minimum grade: B+ recorded for reporting
  Pass  Critical findings: 0 (max allowed: 0)
  Pass  High findings: 2 (max allowed: 5)
  Advisory  Coverage: 72% observed from repository artifacts

  --- Evidence Pack -------------------------------

  Pack ID     ep_cf79c0d0d9b7
  SHA-256     cf79c0d0d9b7f708a49b...
  Integrity   HASH VERIFIED

3. Review the saved report

bashCertus

cat certus-report-express-2026-03-23.json | jq '.grade, .score, .summary'

4. Inspect findings in detail

bashCertus

# Open the terminal dashboard
certus dashboard

# Or export as HTML
certus audit --framework SOC-2

GitHub App

Use merge-gate enforcement without YAML.

For the hosted product, approved pilot organizations install the managed Certus GitHub App from the dashboard on selected repositories. Certus scans PRs, publishes the certus/compliance status, comments findings, and lets GitHub branch protection enforce the result.

Hosted product install path

bashCertus

1. Sign in to https://www.getcertus.cloud/login
2. Open Dashboard -> Integrations -> GitHub
3. Use the pilot workspace issued to your organization
4. Install the Certus GitHub App only on approved pilot repositories
5. Return to the dashboard and confirm the installation is connected

textCertus

Hosted product
  - Certus manages the GitHub App private key
  - Certus manages the webhook secret
  - Certus owns the hosted receiver
    https://www.getcertus.cloud/api/webhooks/github
  - Certus posts the required status context:
    certus/compliance
  - GitHub enforces blocking only when branch protection
    or a ruleset requires certus/compliance

Self-hosted / operator flow only
  certus github setup

Use the setup wizard only when you operate your own Certus deployment
and your own GitHub App. Hosted product users should not enter App keys
or webhook secrets into the CLI.

What happens after install

1. A compliance scan is triggered by webhook.
2. Certus posts the certus/compliance commit status and, when permissions allow, a Check Run named Certus Compliance.
3. A detailed PR comment shows findings and remediation guidance.
4. GitHub blocks the merge only when branch protection or a ruleset requires certus/compliance.
5. A signed evidence pack is stored for reviewers and auditors.

No CI YAML is required for the hosted GitHub App path. Pilot orgs install the app from the dashboard, select approved repositories, then require certus/compliance in GitHub branch protection or rulesets. Add an optional .certus.yml only when you need repo-specific policy. The CLI wizard remains for self-hosted operators only.

Strict audit-grade blocking

Audit grade and merge gate are intentionally separate. By default, grade is posture context and the gate blocks on enforceable critical and high findings. Turn on strict grade enforcement when the team wants a grade below min_grade to fail the PR.

.certus.yml

yamlCertus

merge_gate:
  enabled: true
  block_on_failure: true
  max_critical: 0
  max_high: 5
  min_grade: C
  enforce_audit_grade: true

Real Repo Example

Authenticate, scan a repository, then scan a PR.

This is the full product path: connect GitHub, scan a repo, run a PR-grade merge gate, and verify the evidence output.

Authenticate

bashCertus

# Hosted product: install the managed GitHub App from the dashboard,
# then connect the CLI to the active workspace
certus login   --api-url https://www.getcertus.cloud   --api-key <org-api-key>   --org <org-slug>

# Optional: GitHub token for CLI-only GitHub API access
certus github login
# Paste a short-lived token when prompted; do not commit it
# Scope access to the minimum repositories required

Scan a repository

bashCertus

certus github scan acme-corp/payment-api

textCertus

  Mode       GitHub Authenticated Scan
  Target     acme-corp/payment-api
  Branch     main
  Visibility private
  Commit     a1b2c3d4e5f6

  Running 5 scanner passes ................. done
  Running compliance blueprints ............ done
  Mapping to compliance controls ........... done
  Signing evidence pack .................... done

  --- Scan Results --------------------------------

  Grade       A-  (91/100)
  Verdict     PASSED
  Controls    27/29 passed
  Blueprints  16/18 passed

  Report saved to certus-report-payment-api-2026-03-23.json

Scan a specific PR

bashCertus

certus github pr acme-corp/payment-api 42

textCertus

  Mode       PR Compliance Scan
  Target     acme-corp/payment-api
  PR         #42

  Title      Add Stripe webhook handler
  Author     jane-dev
  Branch     feature/stripe-webhooks -> main
  Changes    +284 / -12 across 8 files

  Creating check run (in_progress) ......... done
  Cloning PR branch ........................ done
  Running 5 scanner passes ................. done
  Running compliance blueprints ............ done
  Completing merge gate - PASSED ........... done
  Commit status certus/compliance .......... done
  Posting PR comment ....................... done
  Evidence stored (ep_8f3a2b1c)

  PR #42 scan complete - PASSED

Preview, comment-only, and verify evidence

bashCertus

# Preview what would be posted (dry run)
certus github pr acme-corp/payment-api 42 --dry-run

# Post only a comment (skip check run)
certus github pr acme-corp/payment-api 42 --comment-only

# List all evidence packs
certus evidence list

# Verify a specific pack
certus evidence verify ep_8f3a2b1c

Command Reference

The CLI surface, grouped by how teams actually use it.

The commands below reflect the current CLI shape in the package source: scanning, GitHub integration, configuration, evidence workflows, reporting, hooks, and diagnostics.

Core - Scanning & Analysis

certus scan <repo> [--ai]

Primary command. Clones a repo or GitHub URL, runs all 5 scanners, executes 18 blueprints, maps findings to the package control registry, signs evidence, and generates an AI assessment.

certus verify [--repo owner/name]

Run compliance verification with framework control display.

certus init

Initialize a .certus.yml workspace configuration file in the current repo.

certus risk <path>

Pre-merge risk prediction with risk score, evidence completeness, and control coverage.

certus fix [--dry-run] [--yes]

Generate and apply patches for common compliance gaps.

GitHub Integration

certus github setup

Self-hosted/operator GitHub App wizard. Hosted-product users should install the managed app from the dashboard instead.

certus github login

Authenticate with a short-lived token when CLI-only access is required.

certus github status

Show GitHub connection status, organizations, and API rate limits.

certus github repos [--org <name>]

List accessible repositories, optionally filtered by organization.

certus github scan <owner/repo>

Scan a private or public GitHub repository with full authentication.

certus github pr <owner/repo> <number>

Run the merge gate workflow for a PR, publish status, comment, and signed evidence.

certus github comment <owner/repo> <number>

Post or update a compliance comment on a PR.

certus github check <owner/repo> <sha>

Create a Check Run for a specific commit SHA.

Configuration & Authentication

certus config show

Display current configuration and key sources.

certus config setup

Interactive setup wizard for API keys and settings.

certus config set <key> <value>

Set api-url, api-key, org, or other approved workspace settings.

certus config reset

Reset all configuration to defaults.

certus login [--api-url] [--api-key] [--org]

Authenticate with the Certus platform API.

certus status

Check API connectivity, authentication state, and workspace info.

certus ping

Measure API connectivity and response time.

Evidence & Compliance

certus evidence list

List all evidence packs, local first and API second.

certus evidence get <id>

Get detailed evidence pack information.

certus evidence verify <id>

Verify SHA-256 hash and optional JWS signature integrity.

certus evidence export <id> [--format json or pdf]

Export an evidence pack.

certus evidence query [--pr 42] [--repo owner/name]

Find evidence packs by PR number or repository.

certus blueprint list

List all 18 compliance blueprints.

certus blueprint run <slug> [--pr 42]

Run a specific blueprint against a PR or codebase.

certus blueprint preview <slug>

Preview what a blueprint checks without running it.

certus policy list [--framework HIPAA]

List framework controls, optionally scoped to a framework.

certus policy validate <file>

Validate a policy definition file.

Analysis & Reporting

certus history

Show scan history with compliance grade trends over time.

certus dashboard

Open the terminal dashboard with grade, trends, and top findings.

certus cost

Estimate regulatory fine exposure and remediation effort.

certus audit --framework SOC-2

Generate a compliance audit document in HTML.

certus explain SOC-2:CC6.1

Explain a compliance control in plain English, offline.

certus compare old.json new.json

Compare two scan reports side-by-side.

certus drift

Detect compliance drift from the last passing baseline.

certus benchmark

Compare compliance posture against built-in illustrative industry baselines.

certus attest --framework HIPAA

Generate a hashed compliance attestation summary from report data.

certus export --format sarif

Export in SARIF, HTML, Markdown, CSV, or OSCAL format.

certus runback [--pr 42]

Replay stored verification context from local report files.

Git Hooks + Diagnostics

certus activate

Install pre-commit and pre-push hooks for automatic compliance scanning.

certus deactivate

Remove Certus git hooks and restore backups.

certus doctor

Diagnose installation, configuration, and connectivity.

certus logs

View scan and verification logs.

certus diagnostics export

Export diagnostic information for troubleshooting.

Evidence Signing

Every scan produces a tamper-evident evidence pack.

Auditors can independently verify integrity without access to the Certus platform. Certus first hashes canonical JSON, then optionally adds an HMAC-SHA256 JWS signature for non-repudiation.

How it works

Layer 1 - SHA-256 content hash. Evidence is hashed over a recursively deep-sorted canonical JSON representation so semantically identical objects produce identical hashes.

Layer 2 - HMAC-SHA256 JWS. When EVIDENCE_SIGNING_KEY is set, Certus emits {sha256-hash}::{base64-header}.{base64-payload}.{base64-signature}.

bashCertus

# Generate a signing key
openssl rand -hex 32

# Set it for all scans
export EVIDENCE_SIGNING_KEY=your-generated-key

# Scan - evidence will be automatically signed
certus scan your-org/your-repo --ai

# Verify
certus evidence verify ep_abc123

Verdict	Meaning
FULLY VERIFIED	SHA-256 hash matches and JWS signature is valid
HASH VERIFIED	SHA-256 hash matches and no JWS was attached
HASH VALID, JWS unverifiable	Hash is correct but the JWS failed validation
INTEGRITY FAILURE	Hash mismatch, evidence was modified after signing

Scanners + Blueprints

Parallel scanners feed blueprint-level compliance reasoning.

Scanners gather raw findings. Blueprints perform deeper file-level analysis and map outcomes into control language that policy gates and reviewers can consume.

Scanner behavior

These scanners are evidence inputs, not a claim of perfect coverage. Merge blocking depends on scanner trust, explicit authored control coverage, and rule applicability to the repo language under review, not on scanner presence alone. Executed tests, dependency evidence, direct secret matches, and applicable Semgrep-backed rule coverage can participate in blocking today; the current IaC path remains advisory.

Scanner	What it reports
TestScanner	Executes the declared test suite when Certus can run it; otherwise falls back to framework discovery, test-file analysis, and coverage artifacts
SastScanner	Semgrep-backed static analysis when Semgrep is available and the rule bundle applies to the repo language, with advisory fallback pattern checks when it does not
SbomScanner	Dependency inventory, OSV advisory matches, license issues, and CycloneDX SBOM generation
IaCScanner	OPA-backed blocking for explicitly bound Kubernetes workload configuration controls; Terraform, Docker, and CloudFormation checks remain advisory
SecretsScanner	Direct file-content matching for API keys, tokens, passwords, private keys, and connection strings

#	Blueprint	What it checks	Key frameworks
1	Security Headers	HSTS, CSP, X-Frame-Options, and CORS configuration	SOC-2, PCI-DSS
2	Auth Hardening	MFA, session management, and password policies	SOC-2, HIPAA, ISO-27001
3	Audit Logging	Audit trail completeness and log integrity	SOC-2, HIPAA, PCI-DSS
4	Dependency Hygiene	Vulnerable, outdated, or unmaintained dependencies	SOC-2, NIST-800-53
5	Secrets Rotation	Rotation policies and hardcoded credentials	PCI-DSS, ISO-27001
6	PII Redaction	PII exposure in logs, responses, and error messages	HIPAA, GDPR
7	Runtime Shielding	Rate limiting, helmet, and CSRF protections	SOC-2, PCI-DSS
8	Control Map	Control mapping coverage and gap analysis	All
9	Cloud Posture	AWS, GCP, and Azure configuration security	NIST-800-53, FedRAMP
10	Input Validation	Input sanitization and validation patterns	PCI-DSS, NIST-800-53
11	Error Handling	Stack trace exposure and graceful degradation	SOC-2, ISO-27001
12	Data Encryption	Encryption at rest and in transit plus key management	HIPAA, PCI-DSS, GDPR
13	Access Control	RBAC, authorization checks, and privilege escalation	SOC-2, HIPAA, ISO-27001
14	API Security	API auth, rate limiting, and input validation	PCI-DSS, NIST-800-53
15	Container Security	Dockerfile best practices, non-root, and multi-stage checks	CIS, NIST-800-53
16	CI/CD Security	Pipeline security, pinned actions, and secret scanning	SOC-2, NIST-800-53, CIS
17	Network Security	TLS config, CORS, firewall rules, and DNS security	PCI-DSS, NIST-800-53
18	Incident Response	IR documentation, monitoring, and backup recovery	SOC-2, HIPAA, NIST-800-53

Frameworks and SDK

Use Certus from code, not just the terminal.

The package exports the pipeline, signing helpers, scanners, frameworks, and configuration helpers. The dashboard then becomes the browser surface for the same evidence stream.

Framework	Controls	Description
SOC 2	36	Trust Services Criteria
HIPAA	34	Security Rule safeguards
PCI-DSS	34	Payment Card Industry DSS v4.0
ISO 27001	40	Annex A information security controls (2022)
NIST 800-53	36	Federal information security controls Rev 5
GDPR	21	EU General Data Protection Regulation
FedRAMP	32	Federal Risk and Authorization Management
CMMC	26	Cybersecurity Maturity Model Certification
CCPA	20	California Consumer Privacy Act
HITRUST	30	Health Information Trust Alliance CSF
NIST CSF	25	NIST Cybersecurity Framework
CIS	18	Center for Internet Security Controls
SOX	20	Sarbanes-Oxley Act IT controls
FISMA	20	Federal Information Security Modernization Act
FERPA	15	Family Educational Rights and Privacy Act
GLBA	15	Gramm-Leach-Bliley Act
NERC CIP	15	North American Electric Reliability Corporation
PIPEDA	12	Personal Information Protection (Canada)
LGPD	15	Lei Geral de Protecao de Dados (Brazil)
APRA CPS 234	15	Australian Prudential Regulation Authority
CSA STAR	20	Cloud Security Alliance STAR
ITAR	15	International Traffic in Arms Regulations
COBIT	20	Control Objectives for IT
SOC 3	15	Trust Services Criteria (public report)

SDK import surface

typescriptCertus

import {
  CertusClient,
  EvidencePipeline,
  signData,
  verifySignature,
  mapToControls,
  TestScanner,
  SastScanner,
  SbomScanner,
  IaCScanner,
  SecretsScanner,
  getAllFrameworks,
  getFramework,
  runAllBlueprints,
  runBlueprints,
  getRegisteredSlugs,
  loadConfig,
  saveConfig,
  clearConfig,
  isAuthenticated,
} from '<pilot-issued-package>'

Run a full scan

typescriptCertus

const pipeline = new EvidencePipeline()
const result = await pipeline.run({
  repoFullName: 'acme/api',
  prNumber: 42,
  headSha: 'abc123def456',
})

console.log(result.status)           // 'complete'
console.log(result.coveragePercent)  // 94
console.log(result.criticalFindings) // 0
console.log(result.signatureHash)    // "hash::jws"

Run individual scanners

typescriptCertus

const ctx = { repoFullName: 'acme/api', prNumber: 42, headSha: 'abc123' }

const [tests, sast, sbom, iac, secrets] = await Promise.all([
  new TestScanner().scan(ctx),
  new SastScanner().scan(ctx),
  new SbomScanner().scan(ctx),
  new IaCScanner().scan(ctx),
  new SecretsScanner().scan(ctx),
])

Sign and verify evidence

typescriptCertus

const hash = await signData(evidenceData)

process.env.EVIDENCE_SIGNING_KEY = 'your-secret'
const hashWithJws = await signData(evidenceData)

const isValid = await verifySignature(data, hashWithJws) // true

Dashboard & CLI Connection

Connect local CLI work to the Certus web platform.

The dashboard at getcertus.cloud is the browser surface for scan results, repository management, evidence history, and compliance trends.

CLI to dashboard

bashCertus

# 1. Log in to the dashboard at https://www.getcertus.cloud/login

# 2. Copy your organization API key from Settings

# 3. Connect the CLI
certus login   --api-url https://www.getcertus.cloud   --api-key <your-org-api-key>   --org <your-org-slug>

# 4. Verify the connection
certus status

Dashboard data is shared across authorized members of the active organization. It is not a separate private dashboard for each individual user.

Surface	URL
Marketing + product	https://www.getcertus.cloud
Documentation	https://www.getcertus.cloud/docs
Login	https://www.getcertus.cloud/login
Dashboard	https://www.getcertus.cloud/dashboard
Changelog	https://www.getcertus.cloud/changelog

Configuration

Config file, environment, and workspace bootstrap.

Configuration is stored in ~/.certus/config.json with strict file permissions. Workspace-level config is created with certus init.

Config file commands

bashCertus

certus config show
certus config setup
certus config set api-key <certus-api-key>
certus config reset

The config file lives at ~/.certus/config.json and should be permissioned to 600.

Workspace bootstrap

bashCertus

certus init

Variable	Purpose
CERTUS_API_URL	Override API base URL
CERTUS_API_KEY	API key, overrides stored config
CERTUS_ORG_SLUG	Organization slug
CERTUS_AI_PROVIDER	Optional managed AI provider selection
GITHUB_TOKEN	Optional short-lived token for CLI-only authenticated scans
EVIDENCE_SIGNING_KEY	HMAC-SHA256 key for JWS evidence signatures
CERTUS_DASHBOARD_SYNC	Enable or disable dashboard sync

Requirements

Runtime prerequisites.

The CLI uses modern Node APIs, local Git, and npm. The evidence signing path uses Web Crypto.

Node.js 20+

Required for the current CLI runtime and release support boundary.

npm 9+

Required for package installation and global CLI usage.

Git

Required for repository cloning and authenticated scans.