Configuration¶

OSS IQ reads settings from command-line flags, environment variables and a config file. Part of the reference.

For each setting, the first source that sets it wins:

1. Command-line flags

2. Environment variables

3. The config file

4. Built-in defaults

Configuration directory¶

OSS IQ keeps its files in ~/.config/ossiq/, or in $XDG_CONFIG_HOME/ossiq/ when XDG_CONFIG_HOME is set:

The GitHub login is not in this directory; it lives in the system secret store.

Config file¶

The config file uses dotenv format: KEY=value lines and # comments. Any OSSIQ_* variable from the Settings table can go in it:

# ~/.config/ossiq/config
OSSIQ_COOLDOWN_PERIOD=14
OSSIQ_CACHE_TTL=48

To read a different file, pass it before the command: ossiq --config ./ossiq.conf status. That file then replaces the default one.

OSS IQ also reads ~/.ossiq/config, where the file lived before. When both files set a key, the one in the configuration directory wins.

Settings¶

Every setting has a global flag, an environment variable, or both. Global flags go before the command, for example ossiq --cutoff-date 2025-01-01 --cooldown-period 14 status.

GitHub token¶

A scan with a GitHub token can make 5,000 GitHub API requests an hour; without one, 60. To log in, see auth and Log in to GitHub.

Token precedence¶

Scans use the first token found, in this order:

1. The global --github-token (-T) flag. Avoid it: a token on the command line shows up in shell history and process listings.

2. The OSSIQ_GITHUB_TOKEN environment variable.

3. The GITHUB_TOKEN environment variable.

4. The stored GitHub login.

5. OSSIQ_GITHUB_TOKEN in the config file. The file is plaintext, so prefer the login.

A token from the flag or the environment never touches the secret store. ossiq auth status shows which source won.

When a scan logs in¶

A scan that finds no token starts the login itself and shows the code on stderr. With a terminal it waits for approval; without one it exits with status 75. Only scanning commands log in: status, html, export, info, add, update-context, plan and apply.

A scan skips the login, and runs at 60 requests an hour, when:

• OSSIQ_GITHUB_AUTH is off, in the environment or the config file;

• the CI environment variable is set to anything but 0 or false;

• the machine has no usable secret store.

In the first two cases the scan ignores the stored login as well. The MCP server offers the login once per session; after a cancelled or expired code, its scans run without a token.

Storage¶

The login lives in the operating system’s secret store, through the keyring library:

The pending entry holds GitHub’s device code, which stays secret until the login is approved.

Tokens¶

• Scope: none. The token can read public data only.

• Lifetime: the access token lasts 8 hours, and OSS IQ refreshes it before it expires. The refresh token lasts about 6 months. GitHub replaces both on every refresh.

• Validation: OSS IQ checks a stored token with one GET /user request, at most once every 10 minutes per process. A revoked token is discarded, and the next scan offers a new login.

• Never written or printed: no token, and no device code, appears in config files, mcp.json, the HTTP cache, logs, --verbose output, exports or HTML reports.

Data sources¶

A scan reads public data from these hosts. Allow them through a firewall or proxy:

When a source is unreachable, the scan still finishes and reports what is missing. See Partial data.