go_over

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

logo

🔽 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, wgetorhttpie 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

demo

🏴 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