ades

README

Actions Dangerous Expressions Scanner

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

Usage

Run the tool from the root of a GitHub repository:

ades .

and it will report all detected dangerous uses of GitHub Actions Expressions.

You can also use the containerized version of the CLI, for example using Docker:

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

Or you can use Go to build from source and run the CLI directly, for example using go run:

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

Features

• Scans workflow files and action manifests.
• Reports dangerous uses of expressions in run: directives, actions/github-script scripts, and known problematic action inputs.
• (Experimental) 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. The schema is intended to be stable from one version to the next for longer periods of time.

Background

A GitHub Actions Expression is a string like:

${{ <expression> }}

that may appear in a GitHub Actions workflow or manifest and is filled in at runtime. If the value is controlled by a malicious actor it could be used to hijack the continuous integration pipeline of a repository. GitHub blogged about this problem in August of 2023.

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 dynamic and making changes some time after a piece of code was introduced can be harder when compared to when the code is being written - thus reporting when a dangerous expression is introduces simplifies the mitigation process.

Related Work

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, similar to ades.

Performs taint analysis tracking known problematic expressions across workflows, steps, and jobs and into and out of JavaScript Actions. It only takes into account known problematic expressions that use github context values. 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).

It may find problematic expressions as a result of a (unknown) vulnerability in an Action, which ades won't report because it is considered out of scope (and arguably better left for dedicated tooling).

Lastly, a seemingly unrelated change in a workflow might change the result of the taint analysis and result in a new warning, thus requiring constant usage of ARGUS, which is relatively expensive.

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, which is also covered by ades.

When it reports on problematic expression in run: scripts it only considers known problematic expression that use github context values. 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 in actions/github-script scripts, when compared to ades (more false positives).

CycodeLabs/raven

An open source tool developed by a commercial company. It aims 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. As a result it will report fewer expressions overall (fewer false positives) but miss some compared to ades (more false positives).

BoostSecurity.io/poutine

An open source tool developed by a commercial company. It 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 miss some compared to ades (more false positives).

Other

There's other work being done in the scope of securing GitHub Actions Workflows and Actions that do not focus on expression but are still worth mentioning:

• aeisenberg/codeql-actions-queries (CodeQL queries for GitHub Actions)
• A Preliminary Study of GitHub Actions Dependencies
• Characterizing the Security of Github CI Workflows
• On the outdatedness of workflows in the GitHub Actions ecosystem
• StepSecurity

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

• Variables
• func Explain(ruleId string) (string, error)
• func Fix(violation *Violation) ([]fix, error)
• func Suggestion(violation *Violation) (string, error)
• type ExprMatcher
• type JobStep
• type Manifest
  • func ParseManifest(data []byte) (Manifest, error)
• type ManifestRuns
• type StepUses
  • func ParseUses(step *JobStep) (StepUses, error)
• type Violation
  • func AnalyzeManifest(manifest *Manifest, matcher ExprMatcher) []Violation
  • func AnalyzeWorkflow(workflow *Workflow, matcher ExprMatcher) []Violation
• type Workflow
  • func ParseWorkflow(data []byte) (Workflow, error)
• type WorkflowJob

Variables

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
)

Functions

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.

func Suggestion

func Suggestion(violation *Violation) (string, error)

Suggestion returns a suggestion for the violation.

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 JobStep

type JobStep struct {
	With map[string]string `yaml:"with"`
	Env  map[string]string `yaml:"env"`
	Name string            `yaml:"name"`
	Run  string            `yaml:"run"`
	Uses string            `yaml:"uses"`
}

JobStep is a (simplified) representation of a workflow job step object.

type Manifest

type Manifest struct {
	Runs ManifestRuns `yaml:"runs"`
}

Manifest is a (simplified) representation of a GitHub Actions Action manifest.

func ParseManifest

func ParseManifest(data []byte) (Manifest, error)

ParseManifest parses a GitHub Actions Action manifest file into a Manifest struct.

type ManifestRuns

type ManifestRuns struct {
	Using string    `yaml:"using"`
	Steps []JobStep `yaml:"steps"`
}

ManifestRuns is a (simplified) representation of an Action manifest's `runs:` object.

type StepUses

type StepUses struct {
	// Name is the name of the Action that is used. Typically <owner>/<repository>.
	Name string

	// Ref is the git reference used for the Action. Typically a tag ref, branch ref, or commit SHA.
	Ref string
}

StepUses is a structured representation of a workflow job step `uses:` value.

func ParseUses

func ParseUses(step *JobStep) (StepUses, error)

ParseUses parses a Github Actions workflow job step's `uses:` value.

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 *Manifest, matcher ExprMatcher) []Violation

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

func AnalyzeWorkflow

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

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

type Workflow

type Workflow struct {
	Jobs map[string]WorkflowJob `yaml:"jobs"`
}

Workflow is a (simplified) representation of a GitHub Actions workflow.

func ParseWorkflow

func ParseWorkflow(data []byte) (Workflow, error)

ParseWorkflow parses a GitHub Actions workflow file into a Workflow struct.

type WorkflowJob

type WorkflowJob struct {
	Name  string    `yaml:"name"`
	Steps []JobStep `yaml:"steps"`
}

WorkflowJob is a (simplified) representation of a workflow job.