Scanner connectors

Scanner connectors attach Shield360 to job-based code scanners. Use them to scan a GitHub repository, collect findings with severity and path, and join those results to coding-agent traces.

Add scanner connectors from Settings → Integrations → Connectors (/connectors) under the Scanners category, or from the Scanner page (/scanner) when no connector exists yet. Connectors are scoped to the current project and environment.

Note

Scanner connectors use the same atomic registry as data-source and memory connectors. They do not participate in telemetry signal routing. GitHub tokens are encrypted on the connector instance.

Mental model

flowchart LR
  subgraph proj [Project + environment]
    SC[Scanner connector]
  end
  SC --> CLI[Trustabl CLI on the Shield360 server]
  CLI --> GH[GitHub repository]
  SC --> ScanPage[Scanner page]
  SC --> Otter[Otter get_scanner_findings]
  ScanPage --> Jobs[Jobs and findings]

• Atomic connectors — one Trustabl scanner per connector instance, with its own target, defaults, and token.
• GitHub URL target — v1 scans https://github.com/owner/repo only. Local filesystem paths are rejected.
• On-demand CLI — Shield360 installs a checksum-verified Trustabl release onto the server, then runs trustabl scan.
• Environment-scoped jobs — jobs and findings stay on the connector for the selected environment.

Supported scanner connectors

Connector	Runtime	What it’s for
Trustabl	Trustabl CLI (latest release at install, v0.1.8 fallback; upgradable)	Scan agent SDKs and MCP servers for reliability and safety findings

Add a Trustabl scanner

A Trustabl connector scans one GitHub repository for agent SDK, MCP and policy findings. The Trustabl CLI runs on the Shield360 server, clones the repository, and returns a report that Shield360 stores as a job with findings.

What you’ll need

• A repository on github.com: https://github.com/owner/repo.
• For private repos, a GitHub token that can read the repo’s contents.
• Outbound HTTPS from the Shield360 server to GitHub, for the CLI download and clones.
• A Linux, macOS or Windows server on amd64 or arm64, for the Trustabl release.

GitHub token permissions. Shield360 passes the token to the CLI as GITHUB_TOKEN and GH_TOKEN so it can clone the repository. Use the narrowest token that can clone:

Token type	Least privilege
Fine-grained personal access token (recommended)	Repository access: only the repositories you scan. Repository permissions: Contents: Read-only (GitHub adds Metadata: Read-only automatically).
Classic personal access token	The repo scope. Classic tokens cannot be limited to read-only or to one repository, so prefer a fine-grained token.

Public repositories need no token. If you point Rules repository at a private rules repo, the same token must be able to read it too. See GitHub’s guide to managing personal access tokens.

Select project and environment

Use the header selectors for the target project and environment.

Open Connectors or Scanner

Go to Settings → Integrations → Connectors and choose Add connector, or open Scanner (/scanner) and choose Add scanner connector from the empty state.

Pick Trustabl

Select Trustabl from the Scanners category.

Install the CLI

In the Trustabl CLI panel of the dialog, click Install CLI. Shield360 looks up the latest release on github.com/trustabl/trustabl, falling back to v0.1.8 if the lookup fails. It downloads the archive for the server’s platform, checks it against the release’s published SHA-256 checksums, and extracts the binary to <cache>/shield360/runtimes/trustabl/<version>/. <cache> is $SHIELD360_RUNTIME_CACHE, else $XDG_CACHE_HOME, else ~/.cache. Use Upgrade CLI later to move to a newer release. You only need to install once per server; the CLI menu on the Scanner page has the same controls.

The download needs outbound access to github.com, api.github.com, objects.githubusercontent.com and release-assets.githubusercontent.com. Air-gapped servers can instead put a trustabl binary on the PATH or set TRUSTABL_BIN to its path.

Set the repository

• Repository URL: https://github.com/owner/repo. Add /tree/<branch> to pin a branch. Only github.com HTTPS URLs work; SSH URLs, local paths, @ and whitespace are rejected.
• Ref (optional): a branch, tag or commit. Leave it blank to use the branch in the URL, or the repository’s default branch.

Choose default scan parameters

These apply when you run with defaults; see Scan parameters. Once the CLI is installed, the dialog reads the CLI’s own flags, so the list can change with the CLI version.

Add the GitHub token

For private repositories, paste the token into GitHub token under Default credentials. It is encrypted on the connector and never sent in a scan request body. When you edit the connector, leave it blank to keep the stored token.

Save and test

Click Save, then Test connection. The test checks only that the CLI is installed; on success it shows the CLI version. It does not check the repository or token, so run a scan to confirm those.

Run a scan

Open Scanner (/scanner), select the connector, and choose Run scan (Run with defaults, or Run with new parameters to override flags once). Findings appear on the same page. Only one scan runs per connector at a time.

Tip

Rules source Follow environment maps this Shield360 environment: production → signed production, staging → signed staging, development → unsigned git.

Note

A scan only ever uses its own connector’s GitHub token. The CLI does not inherit GITHUB_TOKEN, GH_TOKEN or any other secret from the Shield360 server’s environment, and the global and system Git configuration (including credential helpers) is switched off for the scan. A connector with no token scans unauthenticated, so it reaches public repositories only.

Message	What to do
The Trustabl CLI is not installed on this Shield360 server. Install it from the connector, then run a scan.	Click Install CLI in the connector dialog, or use the CLI menu on the Scanner page.
Shield360 could not download the Trustabl CLI release. Check outbound access to GitHub and try again.	Allow the GitHub hosts above through your firewall or proxy, or install the binary yourself and set TRUSTABL_BIN.
The Trustabl CLI download did not match the published checksum. The install was aborted.	Retry. If it keeps failing, check for a proxy that rewrites downloads.
This Shield360 server platform does not have a Trustabl CLI release.	The server’s OS or CPU has no Trustabl build. Run Shield360 on Linux, macOS or Windows, amd64 or arm64.
The Trustabl CLI did not report a version. …	Click Upgrade CLI to reinstall.
A GitHub repository URL is required. / Enter an https://github.com/owner/repo URL. Local paths are not allowed.	Fix Repository URL.
Ref must use letters, numbers, dots, slashes, hyphens, or underscores.	Fix Ref.
GitHub could not find that repository. Check the URL and add a GitHub token on the connector for private repos.	Check the URL. For a private repo, add a token with Contents: Read-only on that repository. A fine-grained token that does not include the repository gives the same error.
A scan is already running for this connector. Wait for it to finish.	Wait, then run again.
This scanner connector must store its token on the connector. …	Edit the connector, enter the GitHub token, and save.
The scanner failed before producing a report.	Turn on Verbose diagnostics (if your CLI version offers it) and run again to see why.

Scanner page

Once a connector is configured, Scanner (/scanner) provides:

Feature	Description
Connector selector	Switch between scanner connectors in the current environment
CLI runtime	Install or upgrade the Trustabl CLI on the Shield360 server
Run scan	Run with connector defaults, or override flags for one job
Jobs	Recent scans with status, score, duration, and error
Findings	Severity, rule, path, and suggested fix for the selected job

Scan parameters

Connector defaults apply when you run with defaults. Override them for one job from Run with new parameters.

Setting	Purpose
Repository URL	GitHub repo to clone. /tree/<ref> is stripped for clone; use it only to pin a branch.
Ref	Optional branch, tag, or commit
Detectors	Comma-separated detector ids (for example claude_sdk,mcp). Blank runs all detectors.
Strict	Mark the job failed if any finding is low or higher
Secret / vuln / license scan	Extra Trustabl scans on repository files and dependencies
Rules source	Follow environment, or pin Production (signed), Staging (signed), or Git (unsigned)
GitHub token	Stored on the connector. Never sent in the scan request body.

Coding agents and Otter

Coding-agent spans stamp vcs.repository.url.full. Shield360 matches that URL to the latest succeeded scan in the current project and environment (https, git@, .git, and /tree/<ref> forms).

• The coding-agent trace detail page shows a Scanner tab when a repo URL is present.
• Otter can call get_scanner_findings with the GitHub URL. Medium+ findings are listed first.

API

Authenticate with a Shield360 API key and send organization, project, and environment headers. See Settings → OpenAPI Spec for the interactive catalog.

Method	Path	Purpose
POST	/api/scanners/{id}/scan	Run a scan. Optional JSON body overrides connector defaults. Returns { connector, job } with findings.
GET	/api/scanners	List connectors in this environment, including recent jobs and findings.
GET	/api/scanners/findings?repoUrl=	Latest succeeded scan for a GitHub repository URL.

POST /api/scanners/{id}/scan can take several minutes (up to 300 seconds). A second scan is rejected while one is already running on the same connector.

Security

• Scan targets are GitHub HTTPS URLs only. Local paths, SSH URLs with credentials, and whitespace are rejected.
• Tokens are encrypted on the connector (enc:v1:…), redacted from jobs and API responses, and never logged.
• The Trustabl CLI download is checksum-verified before install.

Related

Connectors overview

Shared connector registry and project scope.

Data-source connectors

Tempo, Loki, Prometheus, Jaeger, and ClickHouse.

Memory connectors

Claude, LangGraph, Mem0, memmesh, and Zep for agent memory.

Coding agents

How coding-agent traces expose vcs.repository.url.full.