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
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

export ARMIS_API_TOKEN="your-api-token-here"

Scan a repository

armis-cli scan repo ./my-project

Scan a container image

armis-cli scan image nginx:latest

Usage

Global Flags

--token string          API token for authentication (or use ARMIS_API_TOKEN env var)
--api-url string        Armis Cloud API base URL (default: https://api.armis.cloud/v1)
--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)

Scan Repository

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

armis-cli scan repo [path] --tenant-id [tenant-id]

Size Limit: 2GB Example:

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

Scan Container Image

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

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

Size Limit: 5GB Examples:

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

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

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]

jobs:
  security-scan:
    uses: ArmisSecurity/armis-cli/.github/workflows/reusable-security-scan.yml@main
    with:
      pr-comment: true        # Post results as PR comment (default: true)
      fail-on: CRITICAL       # Fail on severity level (default: CRITICAL)
      upload-artifact: true   # Upload SARIF artifact (default: true)
    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)

Required secrets:

api-token: Armis API token for authentication
tenant-id: Tenant identifier for Armis Cloud

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
    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 }}
          fail-on: HIGH,CRITICAL

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
    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_API_TOKEN: ${{ secrets.ARMIS_API_TOKEN }}
        run: |
          armis-cli scan repo . --format sarif --fail-on HIGH,CRITICAL

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_API_TOKEN: $ARMIS_API_TOKEN

Jenkins

pipeline {
    agent any
    environment {
        ARMIS_API_TOKEN = credentials('armis-api-token')
    }
    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_API_TOKEN: $(ARMIS_API_TOKEN)
  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

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

ARMIS_API_TOKEN - API token for authentication
ARMIS_API_URL - Custom API base URL
ARMIS_FORMAT - Default output format

Security Considerations

Size Limits: Enforced to prevent resource exhaustion
- Repositories: 2GB
- Container Images: 5GB
Authentication: API tokens are never logged or exposed
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 126 Commits
.github		.github
cmd/armis-cli		cmd/armis-cli
docs		docs
internal		internal
scripts		scripts
test		test
.armisignore.example		.armisignore.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
LICENSE		LICENSE
Makefile		Makefile
NOTICE		NOTICE
README.md		README.md
action.yml		action.yml
go.mod		go.mod
go.sum		go.sum

License

ArmisSecurity/armis-cli

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

Scan a repository

Scan a container image

Usage

Global Flags

Scan Repository

Scan Container Image

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 9

Packages 0

Uh oh!

Contributors 4

Uh oh!

Languages

Packages