go_over

A tool to audit Erlang & Elixir dependencies, to make sure your ✨ gleam projects really sparkle!

🔽 Install

gleam add --dev go_over

📣 Also!

• add .go-over/ to your .gitignore
• make sure git is installed. (If not running via the BEAM you need curl, wget or httpie installed as well)

🌸 Javascript

If running with Javascript install

{
  "devDependencies": {
    "yaml": "^2.4.3"
  }
}

Bun, Deno & Nodejs are all supported!

▶️ Usage

gleam run -m go_over

🎥 Obligatory VHS

🏴 Flags

• --format Specify the output format of any warnings, [minimal, detailed, json, sarif] (default: None)
• --sarif-output PATH Write SARIF output to PATH instead of stdout (requires --format sarif)
• --puller Specify the tool used to reach out to hex.pm, [native, curl, wget, httpie] (default: None)
• --force: Force pulling new data even if the cached data is still valid
• --outdated: [deprecated] runs gleam deps outdated instead — use that command directly
• --verbose: Print progress as packages are checked
• --root PATH: Audit a single Gleam project at PATH (uses PATH/gleam.toml and PATH/manifest.toml)
• --workspace [PATH]: Audit every Gleam project under PATH (default: .). Finds directories containing both gleam.toml and manifest.toml. Each project’s own [go-over] settings apply during its audit. Set workspace_max_depth in the scan root’s gleam.toml to control discovery depth (default: 3).
• --local: Cache data in the project’s .go-over/ directory
• --global: Cache data in the user’s home directory (shared across projects)
• --help,-h: Print help

Flags override config values if set

⚙️ Config

Optional settings that can be added to your project’s gleam.toml

[go-over]
# force pulling new data even if cached data is still valid
# default: false
force = false
# maximum directory depth when scanning with --workspace (set on the scan root)
# default: 3
workspace_max_depth = 3
# if true all cached data will be stored in user's home directory
# allowing cache to be shared between projects
# default: true
global = true
# sets output format for warnings ["minimal", "detailed", "json", "sarif"]
# default: "minimal"
format = "minimal"
# [deprecated] runs `gleam deps outdated` — use that command directly instead
# default: false
outdated = false
# tool used to pull information from hex.pm ["native", "curl", "wget", "httpie"]
# default: "curl" for JS and "native" for Erlang
puller = "curl"
# licenses dependencies are allowed to use. If left empty then all licenses are allowed
# default: []
allowed_licenses = []

[go-over.ignore]
# will ignore all warnings for indirect dependencies
# default: false
indirect = false
# will ignore all warnings for dev-dependencies. Note: to ignore indirect dependencies regardless of source see go-over.ignore.indirect
# default: false
dev_dependencies = false
# list of package names to skip when auditing dependencies
# default: []
packages = ["example_package"]
# list of warning severities to skip when auditing dependencies
# default: []
# (case insensitive)
severity = ["example_moderate"]
# list of advisory IDs to skip when auditing dependencies
# default: []
ids = ["GHSA-xxxx-yyyy-zzzz"]

⌛ Caching

• Security advisory data is cached for six hours
• hex.pm retired package data is cached for one hour

🪝 pre-commit hooks

You can add go_over to you’re pre-commit hooks by installing 🌵cactus & then adding this to your gleam.toml

[cactus.pre-commit]
actions = [
  { command = "go_over" },
]

⚙️ CI

You can schedule daily runs to keep your deps up to date and open issues when necessary! Example ▶️

- run: gleam run -m go_over -- --local

SARIF output (GitHub Code Scanning)

Use --format sarif to emit a SARIF 2.1.0 log suitable for GitHub’s code scanning upload action:

- run: gleam build
- run: gleam run -m go_over -- --format sarif --sarif-output go-over.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: go-over.sarif

By default SARIF is written to stdout. Use --sarif-output to write directly to a file instead of shell redirection. Run gleam build first so compile output does not mix into stdout. Info-level notices (unnecessary ignores, skipped workspace projects, git dependencies) are included as SARIF note results.

You can validate SARIF output against GitHub ingestion rules at https://sarifweb.azurewebsites.net/Validation.

In workspace mode (--workspace), each Gleam project appears as a separate run in the SARIF document. Pass --format on the CLI to use one format for every project; otherwise each project’s [go-over] format must match.

Upgrading to v4

See CHANGELOG.md for breaking changes from v3.

Other Art

• As I’m sure is no surprise this tool is inspired by (and all around worse than) mirego/mix_audit. Please check it out!
• It also draws inspiration from mix hex.audit

License

This tool uses mirego/elixir-security-advisories which is it self licensed with

• BSD-3-Clause
• CC-BY 4.0 open source
  • See their #license section

Code original to this repo is Licensed under MIT