ades

package module
v0.0.0-...-ad17177 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 14, 2026 License: GPL-3.0 Imports: 10 Imported by: 0

README

Actions Dangerous Expressions Scanner

A simple tool to find dangerous uses of GitHub Actions Expressions.

Expressions in GitHub Actions, e.g. ${{ <expression> }}, may appear in a GitHub Actions workflow or manifest and are filled in at runtime. If the value is controlled by an attacker it could be used to hijack the continuous integration pipeline of a repository. A more detailed description of the problem is given by GitHub in "Understanding the risk of script injections". GitHub also covered this problem on their blog in 2023 and 2025.

ades helps you find and resolve dangerous uses of GitHub Actions Expressions in workflows and manifests.

Overview

Getting Started

Installation
Binary

Download the binary for your platform manually from the latest release or using the CLI, for example using the gh CLI:

gh release download --repo ericcornelissen/ades --pattern ades_linux_amd64.tar.gz

Validate the provenance of the release you downloaded:

gh attestation verify --owner ericcornelissen ades_linux_amd64.tar.gz

Unpack the archive to get the binary out:

tar -xf ades_linux_amd64.tar.gz

Then add it to your PATH and run it:

ades -version

Or, without adding it to your PATH:

./ades -version
Docker / Podman

Install the ades container by pulling it:

docker pull docker.io/ericornelissen/ades:latest

Validate the provenance of the container using cosign:

cosign verify \
  --certificate-identity-regexp 'https://github.com/ericcornelissen/ades/.+' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  docker.io/ericornelissen/ades:latest

Then run it using:

docker run --rm --volume $PWD:/src docker.io/ericornelissen/ades -version

You can set up an alias for convenience:

alias ades='docker run --rm --volume $PWD:/src docker.io/ericornelissen/ades'

NOTE: To use Podman instead of Docker you can replace docker by podman.

Go

Fetch and run ades from source using the Go CLI:

go run github.com/ericcornelissen/ades/cmd/ades@latest -version

Or fetch and install ades from source using the Go CLI, after which it can be run directly:

go install github.com/ericcornelissen/ades/cmd/ades@latest
ades -version

Or integrate ades into a Go project as a tool, after which it can be run without @latest:

go get -tool github.com/ericcornelissen/ades
go run github.com/ericcornelissen/ades/cmd/ades -version
Usage

Run ades from the root of a GitHub repository and it will report all dangerous uses of GitHub Actions Expressions for the project:

ades

Alternatively, specify any number of projects to scan, and it well report for each:

ades project-a project-b

If you need more information, ask for help:

ades -help

Features

  • Scans workflow files and action manifests.
  • Reports dangerous uses of expressions in run: directives, actions/github-script scripts, and known problematic action inputs.
  • Report dangerous uses of expressions in known vulnerable actions.
  • Provides suggested fixes and (experimental) fully automated fixes.
  • Configurable sensitivity.
  • Machine & human readable output formats.
Rules

See RULES.md.

JSON output

The -json flag can be used to get the scan results in JSON format. This can be used by machines to parse the results to process them for other purposes. The schema is defined in schema.json and it is intended to be stable from one version to the next for longer periods of time.

Philosophy

This project aims to provide a tool aimed at helping developers avoid the problem of injection through expressions altogether. Instead of reporting on known problematic uses of expressions, ades reports on all potentially dangerous uses of expressions, nudging developers to use safe alternatives from the get-go.

The motivation behind this is twofold. First, it makes the tool much simpler and faster. Second, it acknowledges that software development is a dynamic process and that future changes can make an expression that is safe today unsafe. Moreover, fixing a workflow while creating it is easier now than it is later.

ARGUS: A Framework for Staged Static Taint Analysis of GitHub Workflows and Actions

A research tool aimed at finding problematic expression in GitHub Action Workflows and Actions. It performs taint analysis to track known problematic expressions across workflows, steps, and jobs and into and out of JavaScript Actions. Because of the taint analysis it will report fewer expressions than ades (fewer false positives), but it might also miss some problematic expressions (more false negatives).

Automatic Security Assessment of GitHub Actions Workflows

A research tool aimed at finding misconfigurations in GitHub Action Workflows (not Actions). It includes looking for problematic expression in run: scripts. It only reports on the use of known problematic expression in run: scripts. Because it considers fewer expressions problematic it will report fewer expressions overall (fewer false positives), but it might also miss other problematic expressions in run: scripts and will completely miss others, for example expressions in actions/github-script scripts.

Ghast

A tool to find misconfigurations in GitHub Actions Workflows (not Actions). Among other checks it looks for a couple known problematic uses of expressions involving the github context. It also steers users away from using inline scripts, recommending local Actions instead. As a result it will report fewer expressions overall (fewer false positives) but miss some (more false negatives).

poutine

A tool that aims to find misconfigurations in CI/CD pipeline configurations including GitHub Actions Workflows. Among other checks it looks for a couple known problematic uses of expressions involving the github context. As a result it will report fewer expressions overall (fewer false positives) but also miss some (more false negatives).

Raven

A tool aimed at finding misconfigurations in GitHub Actions Workflows (not Actions). Among other checks it looks for a couple known problematic uses of expressions involving the github context. As a result it will report fewer expressions overall (fewer false positives) but miss some (more false negatives).

zizmor

A tool that aims to find security issues in GitHub Actions CI/CD setups. It reports various kinds of potential security problems including dangerous uses of expressions ("template injection"). Similar to ades, it will report on most uses of expressions but only in run: and actions/github-script scripts except for a small allowlist of known safe expressions. It does distinguish between expressions known to be attacker controlled and only potentially attacker controlled with different severities.

Others

There is other work being done in the scope of GitHub Actions security that does not focus on GitHub Actions Expression but is still worth mentioning:

Tooling
  • actionlint: General purpose linter for GitHub Actions.
  • aeisenberg/codeql-actions-queries: A CodeQl query pack for writing reusable GitHub Actions.
  • BOLT: Egress-filter and runtime security tool for GitHub Actions pipelines.
  • Bullfrog: Control the outbound network connections of GitHub Actions pipelines.
  • Cimon: Runtime security to stop software supply-chain attacks on GitHub Actions pipelines.
  • CodeQL support for GitHub Actions: CodeQL queries for GitHub Actions workflows.
  • OpenSSF Scorecard: Assess repository configs, including GitHub Action workflows.
  • StepSecurity: Runtime protection for GitHub Actions pipelines.
Research

License

The software is available under the GPL-3.0-or-later license, see COPYING.txt for the full license text. The documentation is available under the GFDL-1.3-or-later license, see GNU Free Documentation License v1.3 for the full license text.

Documentation

Overview

The ades command can be used to Scan for Dangerous Expression in Actions (sdea -> ades) workflows and manifests - Actions being GitHub's continuous integrations platform.

It is primarily intended to be used as a CLI application, but also exports its functionality for programmatic use. For programmatic use, note that this project does not use semantic versioning.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// AllMatcher is an ExprMatcher that will find all GitHub Actions Expressions in strings.
	AllMatcher allExprMatcher

	// ConservativeMatcher is an ExprMatcher that will conservatively find GitHub Workflow
	// Expressions in strings that are known to be controllable by attackers.
	ConservativeMatcher conservativeExprMatcher
)
View Source 
var (
	LiteralInExprRegExp      = regexp.MustCompile(leading + `(true|false|null|-?\d+(\.\d+)?|0x[0-9A-Fa-f]+|-?\d+\.\d+e-?\d+|'[^']+')` + trailing)
	SafeContextInExprRegExp  = regexp.MustCompile(leading + `(github\.(action_status|event_name|event\.number|event\.workflow_run\.id|ref_protected|ref_type|retention_days|run_attempt|run_id|run_number|secret_source|sha|workflow_sha|workspace)|job\.status|jobs\.[a-z-_]+\.result|steps\.[a-z-_]+\.(conclusion|outcome)|runner\.(arch|debug|environment|os)|strategy\.(fail-fast|job-index|job-total|max-parallel)|needs\.[a-z-_]+\.result)` + trailing)
	SafeFunctionInExprRegExp = regexp.MustCompile(leading + `((always|cancelled|contains|endsWith|failure|hashFiles|success|startsWith)\(([^,]*,)*[^,)]*\)|(format|fromJSON|join|toJSON)\([\s,]*\))` + trailing)

	EmptyExprRegExp = regexp.MustCompile(`\${{` + boundary + `*}}`)
)

Functions

func AnalyzeRepo 

func AnalyzeRepo(fsys fs.FS, matcher ExprMatcher) (map[string][]Violation, error)

AnalyzeRepo analyzes a GitHub repository for problematic GitHub Actions Expressions in manifests and workflows.

func Explain 

func Explain(ruleId string) (string, error)

Explain returns an explanation for a rule.

func Fix 

func Fix(violation *Violation) ([]fix, error)

Fix produces a set of fixes to address the violation if possible. If the return value is nil the violation cannot be fixed automatically.

Types

type ExprMatcher 

type ExprMatcher interface {
	// FindAll is the function that returns all relevant GitHub Actions Expressions in the provided
	// input.
	FindAll([]byte) [][]byte
}

ExprMatcher is the interface for types that can find GitHub Actions Expressions in strings.

type Violation 

type Violation struct {

	// JobId is an identifier of a job in a GitHub Actions workflow, either the name or key.
	//
	// This will be the zero value if the violation is for a GitHub Actions manifest.
	JobId string

	// StepId is the identifier of a step in a GitHub Actions workflow or manifest, either the name
	// or index.
	StepId string

	// Problem is the problematic GitHub Actions Expression as observed in the workflow or manifest.
	Problem string

	// RuleId is the identifier of the ades rule that produced the violation.
	RuleId string
	// contains filtered or unexported fields
}

Violation contain information on problematic GitHub Actions Expressions found in a workflow or manifest.

func AnalyzeManifest 

func AnalyzeManifest(manifest *gha.Manifest, matcher ExprMatcher) []Violation

AnalyzeManifest analyzes a GitHub Actions manifest for problematic GitHub Actions Expressions.

func AnalyzeWorkflow 

func AnalyzeWorkflow(workflow *gha.Workflow, matcher ExprMatcher) []Violation

AnalyzeWorkflow analyzes a GitHub Actions workflow for problematic GitHub Actions Expressions.

Source Files

View all Source files

Directories

Path Synopsis
cmd
ades command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.