Safeguard Docs

What Safeguard Can Analyse

Every input Safeguard reads (installers, archives, disk and VM images, containers, mobile and macOS apps, Linux packages, firmware, lockfiles and existing SBOMs), the SBOM and VEX formats it writes, the analyses it runs and the ways to send it files.

What Safeguard Can Analyse

This page is the reference for what you can hand to Safeguard and what you get back. It covers the inputs Safeguard opens, the SBOM and VEX formats it writes, the analyses that run on every input, and the ways files reach the platform.

Safeguard identifies a file by its content (magic bytes and internal layout), not by its name. The extension is only a tie-break, so a renamed installer or an archive without an extension is still recognised. Nothing that Safeguard extracts is ever executed.

To check how Safeguard sees a file before you scan it:

safeguard detect artifact ./setup.exe

Inputs

Windows installers

TypeWhat Safeguard reads
MSI, MSP, MSMOpens the package, rebuilds installed paths from the File, Component and Directory tables, and picks up the cabinets that ship beside it.
CABMicrosoft cabinets, including cabinet self-extractors and InstallShield cabinets.
EXE installersNSIS, Inno Setup, WiX Burn bundles (embedded cabinets are carved out), InstallShield, 7-Zip and ZIP self-extractors, and EXE wrappers around an MSI.
PE executables and DLLsVersion resources, Go build information and .NET assemblies (CLR header and deps.json project libraries).

Archives

TypeWhat Safeguard reads
ZIP (including Zip64)Opened and scanned. Inside a folder, ZIPs that hold program files are opened automatically; pass --unpack on to open every ZIP, TAR and GZIP.
TARPlain, .tar.gz/.tgz, .tar.bz2, .tar.xz and .tar.zst.
Single-file compressiongzip, xz, bzip2 and zstd.
7z and RAR (RAR 4 and 5)Opened through 7-Zip, which the Safeguard scanner image includes.
Java archivesJAR, WAR and EAR, with their Maven metadata.
Package archivesPython wheels and sdists, npm .tgz packages and NuGet packages.

Archives inside archives are opened up to four levels deep. An encrypted archive is reported as encrypted and left unopened.

Disk and VM images

TypeWhat Safeguard reads
OVAThe appliance archive and the disks inside it.
VMDKIncluding stream-optimised VMDK.
QCOW2, VHD, VHDXRead directly, without mounting.
Raw disksGPT and MBR partition tables.
Filesystemsext2/3/4, NTFS, FAT, HFS+ and APFS partitions, plus squashfs and cramfs.

Safeguard prefers the partition that holds the operating system root and catalogues it from its package databases (dpkg, apk, rpm and opkg), so a VM image produces one SBOM for the whole system.

Container images

TypeWhat Safeguard reads
Registry imagessafeguard scan --image <reference>, with --platform for multi-architecture images and registry credentials for private registries.
Image archivesdocker save tarballs and OCI image layouts, compressed or not (docker-archive:, oci-archive:, oci-dir:).
Other sourcesPodman (podman:) and Apptainer .sif images.

Mobile apps

TypeWhat Safeguard reads
APKPackage name and version from the binary manifest, library versions from bundled metadata, and native libraries. App analysis covers the manifest (debuggable, backup, exported components, permissions), signing and the SDK inventory.
AABThe app identity from the bundle manifest and its Maven dependencies from the bundle's dependency metadata.
XAPK, APKS, APKMEvery APK inside the bundle is scanned, and the bundle index is checked for missing splits and OBB files.
IPAThe app and every nested bundle (frameworks, app extensions, watch apps) from their Info.plist files, CocoaPods acknowledgements and an encrypted main binary flag.

macOS

TypeWhat Safeguard reads
DMGUDIF disk images, plus raw HFS+ and APFS images.
PKG and MPKGInstaller packages and their payloads.
App bundles.app folders and the frameworks, plug-ins, XPC services and app extensions inside them, from each Info.plist.
Mach-OThin and universal (fat) binaries, Go build information and dylib install names that carry a full version.

Linux

TypeWhat Safeguard reads
ELFExecutables and shared libraries, including Go build information, Rust crates and bundled Python applications.
DEB, UDEB and IPKPackage metadata and payload.
RPMPackage metadata and payload.
snapThe squashfs filesystem inside the snap.

Firmware

Safeguard finds squashfs and cramfs filesystems in a firmware image by their signatures, including inside U-Boot uImage, FIT and TRX containers and vendor headers, then catalogues what is inside them.

Language binaries

LanguageWhat Safeguard reads
GoEmbedded build information in ELF, PE and Mach-O binaries.
Rustcargo auditable dependency data, or the crates named in embedded registry paths when that data is absent.
PythonPyInstaller bundles (package metadata and module versions) and Nuitka onefile payloads.
.NETdeps.json and assembly version resources.
JavaJAR, WAR and EAR contents.
ElectronThe package.json files inside app.asar.

Source manifests and lockfiles

Point Safeguard at a repository or folder and it reads these files. Lockfiles also add hashes, download URLs and the dependency graph.

EcosystemFiles
JavaScriptpackage.json, package-lock.json, npm-shrinkwrap.json, yarn.lock, pnpm-lock.yaml
Pythonrequirements.txt, Pipfile, Pipfile.lock, poetry.lock, uv.lock, pyproject.toml, setup.py
Java and Kotlinpom.xml, build.gradle, build.gradle.kts, gradle.lockfile, Gradle version catalogs (gradle/*.versions.toml), gradle.properties
Gogo.mod, go.sum
RustCargo.toml, Cargo.lock
.NET*.csproj, packages.config, packages.lock.json
RubyGemfile, Gemfile.lock
PHPcomposer.json, composer.lock
Swift and Objective-CPackage.swift, Package.resolved, Podfile, Podfile.lock
C and C++conanfile.txt, conanfile.py, conan.lock, vcpkg.json, CMake FetchContent, ExternalProject and CPM declarations
Elixirmix.exs, mix.lock
Dart and Flutterpubspec.yaml, pubspec.lock

Git submodules are listed as components too.

Existing SBOMs and VEX

You can bring SBOMs produced elsewhere. Safeguard detects the format from the content, imports the components and matches them against current vulnerability data.

FormatVersions and encodings Safeguard imports
CycloneDXVersions 1.0 to 1.7, as JSON, XML or protobuf
SPDX 2Versions 2.1, 2.2 and 2.3, as JSON, YAML, XML, tag-value, RDF/XML or the SPDX spreadsheet
SPDX 3Version 3.0 as JSON-LD
SWID tagsThe 2009 and 2015 schemas, as XML
Component tableA CSV or XLSX table of components
VEXOpenVEX, CSAF VEX and CycloneDX VEX documents, as JSON

Imported VEX statements accept the statuses not_affected, affected, fixed and under_investigation. Anything in an imported SBOM that could not be read is listed with the SBOM quality results, so you can see what was kept.

Outputs

SBOM formats

FormatVersions and encodings Safeguard writes
CycloneDXVersions 1.2 to 1.7 as JSON or XML, and 1.3 to 1.7 as protobuf. The CLI also writes 1.0 and 1.1 as XML.
SPDX 2Versions 2.2 and 2.3 as JSON, YAML, XML, tag-value, RDF/XML or XLSX. The CLI also writes 2.1 as tag-value or RDF/XML.
SPDX 3Version 3.0 as JSON-LD
SWID tagsThe 2009 and 2015 schemas, as XML
Component tableA CSV or XLSX table of components

The CLI writes SPDX 2.3 JSON and CycloneDX 1.6 JSON by default. Choose others with --sbom-format spdx|cyclonedx|both, or name exact targets with --sbom-target family:version:encoding (repeatable; all, all-cyclonedx and all-spdx write every target in one run). In the console, pick the format from the SBOM download menu on a project or product. See Explore SBOM.

SPDX 2.2 and 2.3 documents follow the official JSON schema, including the PACKAGE-MANAGER spelling of referenceCategory. An SBOM built from a scan that did not finish is marked incomplete (CycloneDX compositions, SPDX document comment), so a downstream tool never mistakes it for a full inventory.

VEX

FormatVersions and where to get them
CycloneDX VEXCycloneDX 1.4 and later, from the console and the CLI (JSON)
OpenVEXOpenVEX 0.0.2 and 0.2.0, from the console
CSAF VEXCSAF 2.0 VEX profile, from the console

VEX documents carry the status of each vulnerability for each component: not_affected (with a justification or impact statement), affected (with an action statement), fixed or under_investigation. In the console, a finding you mark as fixed or resolved becomes fixed, a false positive becomes not_affected, and open, accepted-risk and won't-fix findings stay affected. In the CLI, VEX comes from a vulnerability scan: safeguard scan --sbom-target cyclonedx-vex:1.6:json.

Analyses

Every input above goes through the same analyses once its components are known.

AnalysisWhat it does
Software composition analysisBuilds the component inventory with package URLs, versions, hashes and the dependency graph. See SCA.
VulnerabilitiesMatches components against OSV, GitHub advisories and NVD (including exact CPE matching), with CISA KEV and EPSS on each match. KEV-listed vulnerabilities rank higher in the risk score.
LicencesDeclared and concluded licences per component, plus licence text detection in files. See License Compliance.
SecretsSource and repositories are scanned for secrets. Executables, libraries and every file in an opened installer, archive or disk image are scanned too, by their ASCII and UTF-16 strings, for AWS keys, GitHub, Slack, Stripe and Google tokens and private keys. Matched values are masked.
Malicious packagesComponents that match an OpenSSF malicious-package advisory are raised to Critical. Package names are checked for typosquatting, combosquatting and look-alike characters, and npm and PyPI install hooks are analysed. The Package Firewall blocks malicious, typosquat and dependency-confusion packages at install time.
Mobile app checksManifest, signing and SDK review for Android, Info.plist and bundle review for iOS, with MASTG test coverage.
SBOM qualityEvery SBOM is scored with sbomqs against the default, NTIA and BSI profiles (the CLI adds NTIA 2021 and FSCT). The CLI writes the score next to the SBOM as .quality.json, safeguard sbom score <file> scores any SBOM, and --min-sbom-score fails a build below your threshold.
AttestationSBOM and VEX files generated in the console are signed with an in-toto statement over the file's SHA-256, kept as a Sigstore bundle that verifies against Safeguard's published key. See Attestation & Signing.

Ways to send files

PathHow
Console uploadOn the Integrations page, Upload artifacts takes files, a folder or an archive as one scan set (by default up to 20 GiB per file, 50 GiB per upload and 200 files per set; the sheet shows your workspace's limits). The type is detected in the browser and you can override it. Upload SBOM takes an existing SBOM or VEX file; drag it onto the sheet and the format is detected from the content. See File Uploads.
CLIsafeguard scan artifact <file|folder|archive> scans installers, binaries, archives, images and apps, and --upload sends the result to a project and version. safeguard scan --dir, --repo, --image and --sbom cover source, images and existing SBOMs. safeguard ci scan runs from a pipeline. See CLI Usage.
RunnerA runner on your own machine takes repository, image, folder and SBOM jobs from the platform and uploads only the results, never your source. On Windows, safeguard runner install --service registers a Windows Service with delayed automatic start and restart on failure that scans a folder on a schedule (monthly by default) and uploads each run as a new SBOM version. See Local Runner.
APIPOST https://api.safeguard.sh/scm/api/v1/ci/scans starts a scan with a secret key that has the scans:trigger scope, and GET on the scan returns its status and gate results. See API Reference.

Offline and on-prem

Set SCANNER_OFFLINE_MODE=true and the CLI and runner make no outbound calls of their own: no update checks, no database downloads, no registry or Maven lookups and no third-party telemetry. Load the vulnerability database with safeguard update --scanner grype --import <bundle> (see Signed database bundles); KEV and EPSS data travel inside it. Every connection to the platform uses TLS 1.2 or later, and plain http:// is refused except for localhost. See Offline Deployment.

On this page