# go_over
[](https://hex.pm/packages/go_over)
[](https://hexdocs.pm/go_over/)
[](https://github.com/bwireman/over/blob/main/LICENSE)
[](https://gleam.run/news/v0.16-gleam-compiles-to-javascript/)
[](https://gleam.run)
A tool to audit Erlang & Elixir dependencies, to make sure your ✨ gleam
projects really sparkle!
# 🔽 Install
```sh
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
```json
{
"devDependencies": {
"yaml": "^2.4.3"
}
}
```
Bun, Deno & Nodejs are _all_ supported!
# ▶️ Usage
```sh
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`
```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](https://hex.pm/packages/cactus) & then adding this to your
`gleam.toml`
```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 ▶️](https://github.com/bwireman/go-over/blob/main/.github/workflows/deps.yml)
```yaml
- run: gleam run -m go_over -- --local
```
### SARIF output (GitHub Code Scanning)
Use `--format sarif` to emit a
[SARIF 2.1.0](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning)
log suitable for GitHub's code scanning upload action:
```yaml
- 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](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](https://github.com/mirego/mix_audit). Please check it
out!
- It also draws inspiration from
[mix hex.audit](https://hexdocs.pm/hex/Mix.Tasks.Hex.Audit.html)
# License
This tool uses
[mirego/elixir-security-advisories](https://github.com/mirego/elixir-security-advisories)
which is it self licensed with
- `BSD-3-Clause`
- `CC-BY 4.0 open source`
- See their
[#license section](https://github.com/mirego/elixir-security-advisories?tab=readme-ov-file#license)
Code original to this repo is Licensed under `MIT`