Armis CLI

Enterprise-grade CLI for static application security scanning with Armis Cloud. Integrate security scanning into developer workflows and CI/CD pipelines.

Features

Scan repositories and container images
Multiple output formats: human, JSON, SARIF, JUnit XML
SBOM generation: Generate CycloneDX Software Bill of Materials
VEX generation: Generate Vulnerability Exploitability eXchange documents
CI/CD ready: GitHub Actions, Jenkins, GitLab, Azure, Bitbucket, CircleCI
Configurable exit codes and fail-on severity
Secure authentication, size limits, and best practices

Installation

Homebrew (macOS/Linux)

Prerequisites: Homebrew must be installed first.

brew install armissecurity/tap/armis-cli

Quick Install Script

Linux/macOS:

curl -sSL https://raw.githubusercontent.com/ArmisSecurity/armis-cli/main/scripts/install.sh | bash

The script will automatically:

Install to ~/.local/bin (no sudo required) or /usr/local/bin as fallback
Verify the installation
Check if the command is in your PATH

Windows (PowerShell):

irm https://raw.githubusercontent.com/ArmisSecurity/armis-cli/main/scripts/install.ps1 | iex

Scoop (Windows)

scoop bucket add armis https://github.com/ArmisSecurity/scoop-bucket
scoop install armis-cli

Manual Download

Download the latest release for your platform from the releases page.

Using Go

go install github.com/ArmisSecurity/armis-cli/cmd/armis-cli@latest

Verify Installation

After installation, verify that the CLI is working:

which armis-cli
armis-cli --version

Troubleshooting: "command not found"

If you see "command not found" after installation:

Check if it's installed:

ls -la ~/.local/bin/armis-cli
# or
ls -la /usr/local/bin/armis-cli

Check your PATH:
```
echo $PATH
```

Add to PATH if needed:

For zsh (default on macOS):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

For bash:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

Or open a new terminal window and try again.
Run directly with full path:
```
~/.local/bin/armis-cli --help
```

Verification

All releases include cryptographic signatures, SBOMs, and SLSA Level 3 provenance attestations for supply chain security.

Verify Checksums (Cosign)

# Download the binary, checksums, and signature
curl -LO https://github.com/ArmisSecurity/armis-cli/releases/latest/download/armis-cli-linux-amd64.tar.gz
curl -LO https://github.com/ArmisSecurity/armis-cli/releases/latest/download/armis-cli-checksums.txt
curl -LO https://github.com/ArmisSecurity/armis-cli/releases/latest/download/armis-cli-checksums.txt.sig

# Verify the signature
cosign verify-blob \
  --certificate-identity-regexp 'https://github.com/ArmisSecurity/armis-cli/.github/workflows/release.yml@refs/tags/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --signature armis-cli-checksums.txt.sig \
  armis-cli-checksums.txt

# Verify the checksum
sha256sum --ignore-missing -c armis-cli-checksums.txt

Verify SLSA Provenance (Supply Chain Security)

# Install slsa-verifier
go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@latest

# Download provenance
curl -LO https://github.com/ArmisSecurity/armis-cli/releases/latest/download/armis-cli-linux-amd64.tar.gz.intoto.jsonl

# Verify SLSA Level 3 provenance
slsa-verifier verify-artifact \
  --provenance-path armis-cli-linux-amd64.tar.gz.intoto.jsonl \
  --source-uri github.com/ArmisSecurity/armis-cli \
  armis-cli-linux-amd64.tar.gz

Inspect SBOM (Software Bill of Materials)

# Download SBOM (CycloneDX JSON format)
curl -LO https://github.com/ArmisSecurity/armis-cli/releases/latest/download/armis-cli-linux-amd64.tar.gz.sbom.cdx.json

# View dependencies
cat armis-cli-linux-amd64.tar.gz.sbom.cdx.json | jq '.components[] | {name: .name, version: .version}'

# Or use CycloneDX CLI tools
npm install -g @cyclonedx/cyclonedx-cli
cyclonedx-cli validate --input-file armis-cli-linux-amd64.tar.gz.sbom.cdx.json

Learn more:

Quick Start

Set up authentication

JWT Authentication (Recommended)

Obtain client credentials from the VIPR external API screen in the Armis platform.

export ARMIS_CLIENT_ID="your-client-id"
export ARMIS_CLIENT_SECRET="your-client-secret"

The tenant ID is automatically extracted from the JWT token — no need to set it separately.

Basic Authentication (Legacy)

export ARMIS_API_TOKEN="your-api-token"
export ARMIS_TENANT_ID="your-tenant-id"

Scan a repository

armis-cli scan repo ./my-project

Scan a container image

armis-cli scan image nginx:latest

Usage

Global Flags

Authentication Flags

--client-id string      Client ID for JWT authentication (env: ARMIS_CLIENT_ID) [recommended]
--client-secret string  Client secret for JWT authentication (env: ARMIS_CLIENT_SECRET) [recommended]
--region string         Armis cloud region (env: ARMIS_REGION)
--token string          API token for Basic authentication (env: ARMIS_API_TOKEN) [legacy]
--tenant-id string      Tenant identifier for Basic auth (env: ARMIS_TENANT_ID) [legacy]

General Flags

--format string         Output format: human, json, sarif, junit (default: human)
--no-progress           Disable progress indicators
--fail-on strings       Fail build on severity levels (default: [CRITICAL])
--exit-code int         Exit code to use when failing (default: 1)
--sbom                  Generate Software Bill of Materials (CycloneDX format)
--vex                   Generate Vulnerability Exploitability eXchange document
--sbom-output string    Custom output path for SBOM (default: .armis/<artifact>-sbom.json)
--vex-output string     Custom output path for VEX (default: .armis/<artifact>-vex.json)
--page-limit int        Results page size for pagination (default: 500, range: 1-1000)
--debug                 Enable debug mode for detailed API responses

Scan Repository

Scans a local directory, creates a tarball, and uploads to Armis Cloud for analysis.

armis-cli scan repo [path]

Size Limit: 2GB Example:

armis-cli scan repo ./my-app --format json --fail-on HIGH,CRITICAL

# Generate SBOM and VEX documents
armis-cli scan repo ./my-app --sbom --vex

Scan Container Image

Scans a container image (local or remote) or a tarball.

armis-cli scan image [image-name]
armis-cli scan image --tarball [path-to-tarball]

Size Limit: 5GB Examples:

# Scan remote image
armis-cli scan image nginx:latest
# Scan local image
armis-cli scan image my-app:v1.0.0
# Scan tarball
armis-cli scan image --tarball ./image.tar

Pull Policy

Control how images are fetched before scanning:

# Use local image if available, otherwise pull (default)
armis-cli scan image nginx:latest --pull=missing

# Always pull latest from registry (recommended for CI/CD)
armis-cli scan image nginx:latest --pull=always

# Never pull, require local image (for air-gapped environments)
armis-cli scan image nginx:latest --pull=never

Output Formats

Human-Readable (Default)

Colorful, formatted output with tables and summaries.

armis-cli scan repo ./my-app

JSON

Machine-readable JSON output.

armis-cli scan repo ./my-app --format json

SARIF

Static Analysis Results Interchange Format for tool integration.

armis-cli scan repo ./my-app --format sarif > results.sarif

JUnit XML

Test report format for CI/CD integration.

armis-cli scan repo ./my-app --format junit > results.xml

CI/CD Integration

For advanced patterns (PR scanning with changed files, scheduled scans, container image scanning) and other CI platforms, see the CI Integration Guide.

GitHub Actions

Option 1: Reusable Workflow (Recommended)

The simplest way to integrate Armis scanning. This reusable workflow handles everything: scanning, PR comments, SARIF uploads, and artifact storage.

name: Security Scan
on:
  pull_request:
    branches: [main, develop]

permissions:
  contents: read
  security-events: write
  pull-requests: write

jobs:
  security-scan:
    uses: ArmisSecurity/armis-cli/.github/workflows/reusable-security-scan.yml@main
    with:
      fail-on: CRITICAL,HIGH
    secrets:
      api-token: ${{ secrets.ARMIS_API_TOKEN }}
      tenant-id: ${{ secrets.ARMIS_TENANT_ID }}

Available inputs:

Input	Type	Default	Description
`scan-type`	string	`repo`	Type of scan: `repo` or `image`
`scan-target`	string	`.`	Path for repo scan, image name for image scan
`fail-on`	string	`CRITICAL`	Severity levels to fail on (e.g., `HIGH,CRITICAL`)
`pr-comment`	boolean	`true`	Post scan results as PR comment
`upload-artifact`	boolean	`true`	Upload SARIF results as artifact
`artifact-retention-days`	number	`30`	Days to retain artifacts
`image-tarball`	string		Path to image tarball (for image scans)
`scan-timeout`	number	`60`	Scan timeout in minutes
`include-files`	string		Comma-separated file paths to scan (for targeted scanning)

Required secrets:

api-token: Armis API token for authentication (legacy — JWT support coming soon)
tenant-id: Tenant identifier for Armis Cloud (legacy — not needed with JWT)

Note: The reusable workflow currently accepts Basic auth secrets. For JWT authentication in CI, set ARMIS_CLIENT_ID and ARMIS_CLIENT_SECRET as environment variables directly in your workflow steps (see Manual Installation below).

Option 2: GitHub Action

Use the action directly for more control over your workflow:

name: Security Scan
on: [push, pull_request]
jobs:
  security-scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: ArmisSecurity/armis-cli@main
        with:
          scan-type: repo
          api-token: ${{ secrets.ARMIS_API_TOKEN }}
          tenant-id: ${{ secrets.ARMIS_TENANT_ID }}
          format: sarif
          output-file: results.sarif
          fail-on: HIGH,CRITICAL
      - uses: github/codeql-action/upload-sarif@v4
        if: always()
        with:
          sarif_file: results.sarif

Option 3: Manual Installation

For full control, install and run the CLI directly:

name: Security Scan
on: [push, pull_request]
jobs:
  security-scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - name: Install Armis CLI
        run: |
          curl -sSL https://raw.githubusercontent.com/ArmisSecurity/armis-cli/main/scripts/install.sh | bash
      - name: Scan Repository
        env:
          ARMIS_CLIENT_ID: ${{ secrets.ARMIS_CLIENT_ID }}
          ARMIS_CLIENT_SECRET: ${{ secrets.ARMIS_CLIENT_SECRET }}
        run: |
          armis-cli scan repo . \
            --format sarif \
            --fail-on HIGH,CRITICAL \
            > results.sarif
      - uses: github/codeql-action/upload-sarif@v4
        if: always()
        with:
          sarif_file: results.sarif

GitLab CI

security-scan:
  stage: test
  image: alpine:latest
  before_script:
    - apk add --no-cache curl bash
    - curl -sSL https://raw.githubusercontent.com/ArmisSecurity/armis-cli/main/scripts/install.sh | bash
  script:
    - armis-cli scan repo . --format json --fail-on CRITICAL
  variables:
    ARMIS_CLIENT_ID: $ARMIS_CLIENT_ID
    ARMIS_CLIENT_SECRET: $ARMIS_CLIENT_SECRET

Jenkins

pipeline {
    agent any
    environment {
        ARMIS_CLIENT_ID = credentials('armis-client-id')
        ARMIS_CLIENT_SECRET = credentials('armis-client-secret')
    }
    stages {
        stage('Security Scan') {
            steps {
                sh '''
                    curl -sSL https://raw.githubusercontent.com/ArmisSecurity/armis-cli/main/scripts/install.sh | bash
                    armis-cli scan repo . --format junit > scan-results.xml
                '''
                junit 'scan-results.xml'
            }
        }
    }
}

Azure DevOps

trigger:
  - main
pool:
  vmImage: 'ubuntu-latest'
steps:
- script: |
    curl -sSL https://raw.githubusercontent.com/ArmisSecurity/armis-cli/main/scripts/install.sh | bash
  displayName: 'Install Armis CLI'
- script: |
    armis-cli scan repo . --format junit > $(Build.ArtifactStagingDirectory)/scan-results.xml
  env:
    ARMIS_CLIENT_ID: $(ARMIS_CLIENT_ID)
    ARMIS_CLIENT_SECRET: $(ARMIS_CLIENT_SECRET)
  displayName: 'Run Security Scan'
- task: PublishTestResults@2
  inputs:
    testResultsFormat: 'JUnit'
    testResultsFiles: '**/scan-results.xml'

CircleCI

version: 2.1
jobs:
  security-scan:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - run:
          name: Install Armis CLI
          command: |
            curl -sSL https://raw.githubusercontent.com/ArmisSecurity/armis-cli/main/scripts/install.sh | bash
      - run:
          name: Run Security Scan
          command: |
            armis-cli scan repo . --format json --fail-on HIGH,CRITICAL
workflows:
  version: 2
  scan:
    jobs:
      - security-scan:
          context: armis-credentials

BitBucket Pipelines

pipelines:
  default:
    - step:
        name: Security Scan
        image: alpine:latest
        script:
          - apk add --no-cache curl bash
          - curl -sSL https://raw.githubusercontent.com/ArmisSecurity/armis-cli/main/scripts/install.sh | bash
          - armis-cli scan repo . --format json --fail-on CRITICAL

Environment Variables

JWT Authentication (Recommended):

Variable	Description
`ARMIS_CLIENT_ID`	Client ID for JWT authentication (from VIPR external API screen)
`ARMIS_CLIENT_SECRET`	Client secret for JWT authentication
`ARMIS_REGION`	Armis cloud region (equivalent to `--region` flag)

When using JWT authentication, the tenant ID is automatically extracted from the token.

Basic Authentication (Legacy):

Variable	Description
`ARMIS_API_TOKEN`	API token for Basic authentication
`ARMIS_TENANT_ID`	Tenant identifier (required only with Basic auth)

General:

Variable	Description
`ARMIS_FORMAT`	Default output format
`ARMIS_PAGE_LIMIT`	Results pagination size (default: 500)

Security Considerations

Size Limits: Enforced to prevent resource exhaustion
- Repositories: 2GB
- Container Images: 5GB
Authentication Security:
- Client credentials and API tokens should be stored securely and never committed to version control
- Use JWT authentication (client ID/secret) for production — it supports automatic token refresh and does not require a separate tenant ID
- Rotate credentials periodically
- Credentials are never logged or exposed in output
Secure Transport: All API communication uses HTTPS
Automatic Cleanup: Temporary files are cleaned up after use
CI Detection: Progress bars automatically disabled in CI environments

Severity Levels

CRITICAL - Critical vulnerabilities requiring immediate attention
HIGH - High-severity vulnerabilities
MEDIUM - Medium-severity vulnerabilities
LOW - Low-severity vulnerabilities
INFO - Informational findings

Finding Types

VULNERABILITY – Code vulnerabilities (SAST)
CONTAINER – Container image vulnerabilities
SCA – Software Composition Analysis (dependency vulnerabilities)
SECRET – Exposed secrets and credentials
LICENSE – License compliance risks
IAC – Infrastructure as Code misconfigurations

Exit Codes

0 - Scan completed successfully with no blocking findings
1 - Scan found blocking findings (configurable with --fail-on)
>1 - Error occurred during scan

Releases

New versions are automatically built and published when version tags are pushed. Each release includes:

Pre-built binaries for macOS, Linux, and Windows (amd64 and arm64)
SHA256 checksums for verification
Automated changelog generation

Visit the releases page to download specific versions.

Building from Source

git clone https://github.com/ArmisSecurity/armis-cli.git
cd armis-cli
make build

The binary will be in bin/armis-cli.

Development

# Run tests
make test
# Run linters
make lint
# Build for all platforms
make release

Contributing

We welcome contributions! Please see:

CONTRIBUTING.md for contribution guidelines
CODE_OF_CONDUCT.md for community standards
Issue Templates for reporting bugs or requesting features

Support

For issues, open a GitHub Issue
For security concerns, see SECURITY.md
For questions, contact support@armis.com

License

This CLI is open source software licensed under the Apache License 2.0. It is intended to be used as a client for interacting with the Armis cloud platform APIs. The CLI itself does not contain any proprietary detection logic or security analysis engines. Use of the CLI is subject to the terms of service of the corresponding cloud APIs.

Name		Name	Last commit message	Last commit date
Latest commit History 198 Commits
.github		.github
cmd/armis-cli		cmd/armis-cli
docs		docs
internal		internal
scripts		scripts
test		test
.armisignore.example		.armisignore.example
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
.markdownlint.json		.markdownlint.json
.pre-commit-config.yaml		.pre-commit-config.yaml
.yamllint.yml		.yamllint.yml
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
NOTICE		NOTICE
README.md		README.md
action.yml		action.yml
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

Armis CLI

Table of Contents

Features

Installation

Homebrew (macOS/Linux)

Quick Install Script

Scoop (Windows)

Manual Download

Using Go

Verify Installation

Troubleshooting: "command not found"

Verification

Verify Checksums (Cosign)

Verify SLSA Provenance (Supply Chain Security)

Inspect SBOM (Software Bill of Materials)

Quick Start

Set up authentication

JWT Authentication (Recommended)

Basic Authentication (Legacy)

Scan a repository

Scan a container image

Usage

Global Flags

Authentication Flags

General Flags

Scan Repository

Scan Container Image

Pull Policy

Output Formats

Human-Readable (Default)

JSON

SARIF

JUnit XML

CI/CD Integration

GitHub Actions

Option 1: Reusable Workflow (Recommended)

Option 2: GitHub Action

Option 3: Manual Installation

GitLab CI

Jenkins

Azure DevOps

CircleCI

BitBucket Pipelines

Environment Variables

Security Considerations

Severity Levels

Finding Types

Exit Codes

Releases

Building from Source

Development

Contributing

Support

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 19

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages