Install STIG
STIG has two operating levels. Modeling, checking, and report generation are portable. Automated C/C++ analysis adds a native LLVM/PhASAR toolchain and therefore has a narrower supported host set.
Supported development systems
You can use the STIG model and report workflow on any development system where you can run:
any working Java 21 or newer to start the bootstrap (JDK 25 on Fedora 44);
the repository's Gradle wrapper; and
IntelliJ IDEA.
This includes the normal Windows, macOS, and Linux IDEA environments supported by those dependencies. A local STIG source checkout is not required when the project consumes a published plugin version.
The checked-in bootstrap downloads STIG's exact Java release through Foojay and verifies its pinned archive SHA-256 before starting Gradle. Gradle, compilation and tests use that approved installation, currently Java 25. The launcher first tries JAVA_HOME, then java on PATH, and accepts any working Java 21 or newer. Java 21 is not a required compiler or a second installation when a newer launcher is available. Fedora setup installs java-25-openjdk-devel; Ubuntu 24.04 setup uses its available JDK 21 for this bootstrap step.
The approved release, platform-specific URLs and archive checksums are maintained by scripts/update.sh, subject to the pinned IDEA runtime and normal catalog update holds. Projects using the same pin share one verified JDK under the Gradle user home. Offline hosts need that archive or installation cached before building; another installed patch is not substituted. With the STIG IDEA plugin installed, Gradle imports and task runs provision and select the project's approved Java home automatically, including after a Java pin update. The IDE uses the same verified cache as the wrapper and honours its Gradle user home and offline settings. IDEA itself uses its bundled runtime. See Managing dependencies for the update policy.
Supported systems for automated source analysis
The automated cascading and data-flow analysis workflow is supported on:
Fedora 44;
Ubuntu 24.04.
That workflow builds and runs the native analyzer with pinned LLVM, Clang, Z3, and PhASAR components. Other hosts can still author and check models and generate reports for elements whose source analysis is disabled, but the native analysis toolchain is not supported there.
Start from the project template
Follow Start a STIG project to try the template locally or import a fresh copy directly into your stig-<short-name> checkout. Both workflows include skill installation and report generation. Reports can be generated before committing the imported files; source-repository cleanliness checks are opt-in.
The template uses the Zero-Clause BSD (0BSD) license, which permits use for any purpose, including private or commercial projects, without attribution or retaining the original license notice. You may remove or replace the template's LICENSE when adopting it, and choose your own license or keep your project proprietary.
The stigGenerateHtml task checks the model, builds enabled implementation analysis, and generates the HTML report. Open the URL printed by Gradle. The first run is slower because Gradle may resolve dependencies and build or provision the native analyzer; later runs are incremental.
stigInstallSkill is an explicit user action. It installs the three STIG skills packaged with the effective STIG Gradle plugin version. It works the same way when that plugin comes from Maven Central or from a local sibling composite build. Normal build, report, CI, and publication tasks never install or update user-scoped Codex state.
Complete the IDEA integration
Download and install IntelliJ IDEA.
In Settings | Plugins | Marketplace, install STIG.
Open your project directory in IDEA.
Trust the project when appropriate and wait for Gradle synchronization and indexing to finish.
The IDEA plugin adds live STIG rule inspections and navigation. Kotlin and Gradle support provide completion, find usages, and refactoring for the model itself.
For local report browsing through IDEA's built-in web server, allow local unauthenticated access under Build, Execution, Deployment | Debugger | Built-in Server. Exact wording varies by IDEA version.
Published plugin or local STIG source
A normal project resolves a published ai.exida.stig Gradle plugin and the PhASAR commit pinned by that artifact. Choose the mode by editing the consumer's gradle.properties:
published is the default if stigSource is omitted. Sibling source directories are ignored. For source development, change only stigSource to local; keep stigVersion for switching back. Local mode ignores that version without a warning or error and requires both checkouts:
Local mode uses the current working trees without pulling or resetting them. A missing checkout is an error, never a fallback to a published artifact. SNAPSHOT and -SNAPSHOT have no special source-selection meaning. Internally the two values map to a validated Kotlin enum; the properties file stores their lowercase text names.
In local mode, Gradle builds ../stig before loading the plugin. That build also creates stig-codex-plugin/build/ and embeds its version-matched marketplace archive in the Gradle-plugin resources, so a direct ./gradlew stigInstallSkill always installs the local contract—not a stale released copy.
Users who only generate reports, publish reports, or initialize elements can keep this sibling layout and use the normal Gradle tasks. When the local plugin's report assets need building, Gradle automatically provisions the pinned Node/npm toolchain and builds them without invoking STIG's Node setup shell scripts. No separate setup command is required for those asset-build prerequisites. Consuming a published plugin avoids that STIG source build entirely. Native analysis still builds the packaged analyzer sources and pinned PhASAR locally on first use and reuses the installation afterward. A warm published installation must match both the selected STIG version and packaged PhASAR commit. Local native builds use a separate cache subdirectory, so changing the mode does not overwrite the other installation. See local development for paths, native gates, and source tracking.
Update STIG or repair dependencies
Run one command from the consumer root:
Choose patch, minor, or major to select the latest stable STIG release allowed by that level. --keep-devel (alias: devel) retains stigSource=local, records the actual loaded checkout version in stigVersion, and synchronizes its pins. Model-only updates do not require PhASAR. none keeps the selected STIG source and repairs its dependency locks and checksums. The --patch style is also accepted; --dependencies is an alias for none. Plain stigUpdate selects major from either source: the latest stable STIG release, including major upgrades. It also selects a newer minor or patch when no newer major exists. Release updates switch local consumers to stigSource=published and save the selected stigVersion together after authentication, without an extra source-switch prompt. A local major update does not need the ignored release pin; local minor and patch use a valid stigVersion as their major/minor baseline. --keep-devel requires local mode and leaves the checkout's branch and working files in place. The updater never pulls or commits source changes.
Use this Gradle entry point directly in model projects. Ordinary applications use the same entry point with their application maintenance profile. The STIG source repository retains scripts/update.sh for maintaining the tool itself.
The consumer's checked-in gradle/stig-update.jar runs before Gradle. It selects STIG first, then installs that STIG version's exact Gradle wrapper, distribution SHA-256 and daemon JVM criteria. A local update reads these files from the canonical sibling STIG checkout without prompting or starting the consumer's old Gradle. A published update obtains them from the selected release's signed verification bundle. It never selects a separate "latest Gradle". Keep the updater JAR, scripts/setup.sh, and wrapper scripts in version control so deleting caches does not remove the update entry point. Wrapper regeneration restores the bootstrap hook automatically.
The update also installs that STIG release's Java provisioning pin and compiler convention in the consumer and its included builds inside the consumer directory. This aligns an older explicit compiler setting with the Java feature required by STIG, including preprocessing builds. Managed settings hooks apply the same convention when an included build is run separately. Existing included-build wrappers also receive the selected Gradle runtime. Keep the installed Java metadata, bootstrap and convention files under gradle/, and the settings changes, in version control. Sibling checkouts keep their own Java policy. The exact pin controls the downloaded archive and the runtime used for the build; another installed patch is not substituted. Existing .idea/misc.xml and owned links in .idea/gradle.xml receive the matching language level and portable, versioned STIG Java <exact pin> SDK reference. The IDEA plugin registers that SDK at its provisioned home on import. Keep these shared settings in Git; machine-specific JDK paths are not written there.
The selected updater also transports STIG's version catalog as gradle/stig.versions.toml. Managed settings expose it as stigLibs in the root and actual consumer-owned included builds, including standalone invocations. Use alias(stigLibs.plugins.kotlinJvm) and catalog libraries such as stigLibs.kotlinCompilerEmbeddable instead of independent Kotlin, compiler, Jackson or test-library version literals. Each installed catalog is the same producer-owned file; edit STIG's source catalog to change shared pins. A target release must publish this managed runtime metadata.
One selected STIG release supplies the shared pins for the whole project. Dependency maintenance still resolves each module's own configurations and lockfile. The standalone updater writes missing checksums and locks, then checks them in a fresh strict-verification Gradle process; a release upgrade does not repeat that completed strict pass. Modules with the same repository objects and component-metadata rules reuse source/Javadoc classifier queries within each build and pass. Different repository or metadata-rule contexts and included builds are checked independently.
Published updates install the selected release's updater before starting Gradle. When first adopting these Java alignment changes from a local STIG checkout, an older checked-in updater needs a one-time refresh before stigUpdate --keep-devel can configure included plugins that still select an older Java. From the consumer root, with stigSource=local and the canonical ../stig checkout, run:
The installer accepts Java 21 or newer and updates the launcher and updater from that selected checkout.
Every mode resolves the selected dependencies and IDEA source attachments, repairs dependency locks and missing SHA-256 entries, and checks the result in a fresh strict-verification process. STIG's managed library versions come from the selected release or local source; the updater does not independently upgrade consumer library constraints. No --write-verification-metadata, --write-locks, or repeated invocation is required. The bootstrap sets the necessary write mode before settings plugins load, including when a missing checksum would prevent the ordinary Gradle task from starting. Online maintenance refreshes Gradle's dependency metadata during the write pass, so cached lookups cannot hide metadata that a fresh CI build will request. --offline uses only the available cache and does not force a refresh.
When new checksums are added, the updater displays their count and metadata path and asks for acceptance with [Y/n]: Enter accepts; n declines. End of input does not accept the additions. To accept additions without the prompt:
Existing checksum pins and signing-key policy remain checked even with --yes. Changed pins or failed strict verification fail the update and restore the accepted checksum policy. Candidate metadata is retained under .gradle/stig/ for review. Review new checksums against publisher information; generating a checksum identifies downloaded bytes and does not authenticate their publisher. Normal builds never write verification metadata.
Dependency resolution covers the consumer modules and recursively included builds, including tooling builds without the STIG plugin. It resolves main and test classpaths, settings and project buildscript sources, Gradle sources and bundled Groovy sources. Source queries include dependency-graph components whose binary variants redirect to another module, as used by Kotlin multiplatform libraries. Local mode also covers the included STIG build's development dependencies. Gradle records these checksums in the invoking build's verification metadata; an included build's standalone verification file is unchanged.
Commit the verification metadata with the dependency changes. Developers resolving the same artifact bytes produce the same SHA-256 checksum. Different platforms or project configurations can require additional artifacts, while changed bytes for an already pinned artifact still fail verification. Clearing IDEA caches does not repair missing checksum entries.
This maintenance does not request native compilation, analysis, report generation or model import. Plugin build prerequisites may compile Kotlin and package resources. If another local STIG build already owns the shared Node workspace, the updater fails with a retry message instead of waiting while it holds the consumer configuration lease. Let that build finish before rerunning the update.
Published release handover
The bootstrap queries the STIG plugin marker's Maven release metadata, then authenticates the chosen release's stig-gradle-plugin-<version>-verification.zip and detached signature using GnuPG and the pinned STIG release certificate. Format 2 includes the runtime files and updater JAR as well as dependency verification metadata and public keys. A release without that runtime bundle cannot perform a bootstrap update; publish the complete bundle instead of guessing its Gradle version or dropping verification.
The updater saves the selected release in .gradle/stig/update.json, merges the authenticated policy, changes stigVersion, and starts fresh Gradle processes for the selected plugin and final verification. These handovers all happen in the original command. An interrupted run resumes its saved target when the same command is run again. none cannot replace an unfinished release update. Source-code and build-file migrations remain separate.
Install GnuPG before a published update; stigInstallDeps includes it. The isolated public keyring does not use personal signing keys. Invalid signatures, missing bundles and conflicting checksums stop the update before the new plugin loads. The STIG source repository retains its own scripts/update.sh workflow for changing managed library and tool versions; see the dependency guide.
Proxies and clean reruns
Gradle's user directory contains configuration as well as caches. Removing ~/.gradle can remove ~/.gradle/gradle.properties, including machine-specific proxy settings. Removing only the consumer's .gradle does not remove that user file. UnknownHostException: services.gradle.org reports a Java hostname-resolution failure, not a missing distribution file. A browser may use a managed proxy or PAC configuration that Java does not use; gradle.org and services.gradle.org are also different hosts.
For initial host setup, run ./scripts/setup.sh. If Java needs a proxy, configure stig.proxy.host and stig.proxy.port in the project's gradle.properties, then include --with-proxy-config:
Optional stig.proxy.setupScript names a project-relative helper for preparing a configured proxy service when that proxy is unreachable; stig.proxy.pacUrl is passed to that helper. Leave both empty for a normal host/port proxy. Java itself does not evaluate PAC. --check never runs the helper or installs host tools.
The helper tests the actual distribution URL and its redirects using Java, detects environment and Ubuntu/GNOME proxy settings, and offers to write tested settings to the user's gradle.properties. It creates a missing user Gradle directory, preserves unrelated properties, and backs up an existing file with private permissions. Browser PAC settings need an explicit approved proxy host/port for Java. Credentials stay in the user file.
When an uncached Gradle distribution download fails, ./gradlew reports the failure and exits. It prints ./scripts/setup.sh --with-proxy-config --yes to use the configured proxy without prompts, and the --check variant for diagnosis. Both commands include the selected Gradle user home so setup repairs the same configuration used by the failed invocation. After setup succeeds, rerun the original Gradle command. Normal task invocations, including stigGenerateHtml, do not open proxy setup, start its helper service, write proxy settings or retry the download automatically. Cached/offline builds do not run a preliminary connection probe.
The helper never disables TLS verification or evaluates a PAC script. A corporate certificate error needs the approved Java trust store, and proxy authentication/allowlist failures may need IT configuration. --check is read-only; a HEAD request failure can differ from the real download (the status explains that case). The updater reads user proxy properties before its own requests and preserves launcher JVM settings in its Gradle subprocesses. See Gradle networking.
For a fresh execution of report tasks while retaining machine configuration and downloaded tool distributions:
See the generated Gradle task API for the task contract.
Common first commands
Use an explicit project path for one element:
If the project exposes the STIG launcher through Bazel, the equivalent complete report command is:
See Starting a project, Installing the STIG Codex plugin, and the generated Gradle task API.