Skip to main content

GETTING STARTED WITH GITHUB TOKEN AUDITS IN SWAMP

In this tutorial, we will audit a GitHub token with Swamp. We will pull the @hivemq/github extension, define a behavior bound to one token kept in a file, and run its audit method to record what the token is and which identity it acts as.

What we will build

We are going to create a behavior named ci-token of type @hivemq/github/token. The behavior reads a GitHub token from a file each time it runs, so the token value never goes into the behavior definition. When we run its audit method, Swamp calls the GitHub API as that token and stores a tokenAudit record of the token's validity, type, issuing app and acting identity.

Prerequisites

  • Swamp installed (see Install Swamp) and signed in (see Swamp Account Requirement)
  • A terminal open in an initialized Swamp repository
  • A GitHub token to audit
  • Network access to the GitHub API

Pull the extension

First, we pull the extension that provides the token behavior type:

swamp extension pull @hivemq/github

You will see output like:

INF extension·pull: Pulling "@hivemq/github"@"2026.08.27.1787839782"
INF extension·pull: Identity verified: "@hivemq/github"@"2026.08.27.1787839782"
INF extension·pull: Pulled "@hivemq/github"@"2026.08.27.1787839782"
INF extension·pull: Extracted 21 files:

The repository now has the @hivemq/github/token type that we use in the rest of this tutorial.

Save the token in a file

Next, we put the token in a file outside the repository. We use /run/secrets/github-token. Paste the token into that file on a single line. The behavior reads the file and trims the value each time it runs an audit, so a trailing newline does no harm.

Define the token behavior

Now we create a behavior named ci-token of type @hivemq/github/token and set its tokenFile global argument to the path of that file. The Create and Run a Behavior guide shows the create command and how to pass a global argument. When we are done, the global arguments in the definition look like this:

globalArguments:
  tokenFile: /run/secrets/github-token

Notice that the definition holds the path to the file and not the token itself.

Run the audit

Now we run the audit method:

swamp behavior run ci-token audit

This command calls the GitHub API as the token stored in /run/secrets/github-token and writes a tokenAudit resource for the ci-token behavior.

The record shows whether GitHub accepted the token. It also shows the token type, which is worked out from the token's prefix: a classic personal access token, a fine-grained personal access token, an OAuth token, or a GitHub App user or installation token. The record also holds the OAuth client ID of the app that issued the token, and the login and account the token acts as. Notice that the token value is not in the record.

What we built

We pulled the @hivemq/github extension and kept a GitHub token in a file outside the repository. We then bound a ci-token behavior to that file and ran an audit. Swamp recorded the token's validity, type, issuing app and identity without storing its value.