内観

API & CI 内観

Run Naiscan automatically before you ship. Add one step to your pipeline and it fails the build when a dependency or a target carries a known CVE, so you catch it before deploy, not after.

1 · Any CI system recommended

Install the CLI from the hosted package and run it as a step. It works in GitHub Actions, GitLab CI, Jenkins, anything with a shell. By default it is advisory: it reports findings but exits 0, so your deploy is never blocked. A lockfile check needs no running target, so it's the cleanest pre-deploy check.

# GitHub Actions (advisory: reports, never blocks the deploy)
- name: Naiscan check
  run: |
    pip install https://scanner.globus.dev/naiscan.zip
    naiscan --lockfile composer.lock

# GitLab CI
naiscan:
  image: python:3.12-slim
  script:
    - pip install https://scanner.globus.dev/naiscan.zip
    - naiscan --lockfile composer.lock

Swap --lockfile composer.lock for a host (e.g. naiscan staging.example.com --yes) to scan a deployed preview. Add --fail-on high only if you want the step to fail the pipeline on high/critical findings.

2 · GitHub Action

A reusable composite Action wraps the same thing in one step. The Action lives in a private repo, so only workflows with access to it can use the uses: form. Everyone else uses the CLI recipe in §1 (no access needed). Replace your-org/naiscan with your Action repo and pin a release tag.

# Advisory by default: checks your exact locked versions (OSV + Packagist),
# reports findings, and does NOT fail the job.
- uses: your-org/naiscan@v1
  with:
    lockfile: composer.lock

# Or scan a deployed preview, and opt into a hard gate with fail-on
- uses: your-org/naiscan@v1
  with:
    target: staging.example.com
    fail-on: high   # only if you want the build to fail

Inputs

`lockfile`	Path to a lockfile (composer.lock, package-lock.json, requirements.txt, …). Needs no running target.
`target`	Host or URL to scan (use instead of `lockfile`).
`fail-on`	Optional hard gate: `none·low·medium·high·critical`. Default `none` is advisory and never fails the job.
`format`	Report format: `text·json·md·html` (default `text`).
`out`	Optional file to write the report to (e.g. upload as an artifact).
`extra-args`	Extra CLI flags, e.g. `--no-deep --delay 0.5`.
`create-issue`	Log findings to a rolling GitHub issue instead of failing (default `false`).
`issue-severity`	Severity that warrants the issue (default `high`).
`issue-title` / `issue-labels`	Title and labels for the rolling issue.

Log a ticket instead of failing

Set create-issue: true and the Action stays advisory (never fails the job): on findings it opens one rolling issue and keeps it updated, and auto-closes it when a run comes back clean. Grant the job issues: write.

permissions:
  issues: write          # required to open/close the issue
steps:
  - uses: your-org/naiscan@v1
    with:
      lockfile: composer.lock
      create-issue: true
      issue-severity: high

3 · Advisory by default, gate only if you want to

By default Naiscan is advisory: it reports findings and exits 0, so a deploy is never blocked (there isn't always a fix, and not every CVE is relevant to you). It prints a summary flagging high/critical as "patching recommended" and medium/low as advisory. If you do want a hard gate, set --fail-on to a severity and the step exits 1 when a confirmed finding meets it. Unverified leads never gate.

`--fail-on none`	Default. Advisory: report everything, exit 0, never block the pipeline.
`--fail-on high`	Fail the build on high/critical only (unrated findings don't gate at this level).
`--fail-on medium`	Fail on medium severity and above.
`--fail-on low`	Fail on any confirmed finding (unrated count here too).
`--fail-on critical`	Fail on critical only.

4 · HTTP API

The same endpoints the web app uses. JSON in, JSON out. Useful for your own tooling; for pipelines, prefer the CLI/Action above (they run in your CI, not against this shared service).

# Dependency scan: send a lockfile's contents
curl -s https://scanner.globus.dev/api/lockfile \
  -H 'Content-Type: application/json' \
  -d '{"filename":"composer.lock","content":"<file contents>"}'

# Target scan (public hosts only, see the note below)
curl -s https://scanner.globus.dev/api/scan \
  -H 'Content-Type: application/json' \
  -d '{"target":"https://example.com","authorized":true}'

Both return a JSON report (technologies, findings, tls, security_headers, vulns, …). The /api/scan endpoint blocks private, loopback and cloud-metadata addresses (SSRF protection), so it can only reach public targets. It can't scan a staging host that isn't internet-facing yet. These endpoints are rate-limited per IP (HTTP 429 with a Retry-After header when you exceed it); send a valid x-api-key header for higher limits. For pipelines, prefer the CLI/Action above, which run in your own CI, not against this shared service.

5 · What to check before a deploy

Dependency gate (recommended): scan your lockfile. It's deterministic, needs nothing running, and catches the exact versions you're about to ship, the cleanest pre-deploy check.
Scan the running app: deploy to a public preview/staging URL first, then scan that. The hosted scan API can't reach non-public hosts, so for an internal-only preview run the CLI inside your pipeline (it can reach localhost / an ephemeral container).
Advise, don't block: by default the step reports findings and lets the deploy proceed, since a fix isn't always available and not every CVE is relevant. Turn on create-issue to log a rolling GitHub ticket for the team to patch (see §2). Only add --fail-on high if a team genuinely wants the build to stop.

See the CLI tab for install and the full flag list, and the Lockfile tab to try a dependency scan in the browser.

Only scan systems you own or have explicit written authorization to test. Keep credentials and aggressive options (port scanning, content discovery) in your own CI, not on any shared service.