Service Account Authentication

NCH Service Account tokens allow nctl to authenticate with Nirmata Control Hub (NCH) without requiring a user login. This is the recommended approach for CI/CD pipelines, GitOps workflows, and any automated scanning or publishing process where storing user credentials is not practical.

Overview

By default, nctl authenticates using a user API key (set via nctl login, the NIRMATA_TOKEN environment variable, or ~/.nirmata/config). Service Account tokens provide an alternative authentication path scoped to specific operations, making them well-suited for automation.

Supported Operations

Service Account tokens can be used for the following nctl operations:

Create an NCH Service Account

Before using Service Account authentication, create a Service Account in Nirmata Control Hub and assign it the appropriate role.

1. Log in to Nirmata Control Hub
2. Navigate to Identity & Access from the left sidebar
3. Go to the Service Accounts section and create a new Service Account
4. Assign the reportPublisher role (or a role with equivalent permissions) to allow scan report publishing and policy fetching
5. Copy the generated secret token — this is your NIRMATA_SERVICE_ACCOUNT_TOKEN

The reportPublisher role grants the following access:

Configure the Token

Set the NIRMATA_SERVICE_ACCOUNT_TOKEN environment variable to your Service Account secret. When this variable is set, nctl uses it automatically for all supported operations — no nctl login required.

export NIRMATA_SERVICE_ACCOUNT_TOKEN="<your-service-account-secret>"

Usage Examples

CLI

export NIRMATA_SERVICE_ACCOUNT_TOKEN="<your-service-account-secret>"

# Scan and publish a Kubernetes cluster report
nctl scan kubernetes --cluster --publish

# Scan and publish a local repository
nctl scan repository /path/to/repo --publish

# Scan and publish a Helm chart
nctl scan helm /path/to/chart --publish

# Scan and publish a Terraform plan
nctl scan terraform /path/to/plan.json --publish

# Scan and publish a Dockerfile
nctl scan dockerfile /path/to/Dockerfile --publish

GitHub Actions

name: NCTL Scan
on:
  pull_request:
    branches:
      - main

jobs:
  nctl-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4

      - name: Install nctl
        uses: nirmata/action-install-nctl-scan@v0.0.12

      - name: Scan and publish Kubernetes resources
        env:
          NIRMATA_SERVICE_ACCOUNT_TOKEN: ${{ secrets.NIRMATA_SERVICE_ACCOUNT_TOKEN }}
        run: nctl scan kubernetes --policies controls/pod-security --resources config-files/k8s --publish

Store the Service Account token as a repository or organization secret (NIRMATA_SERVICE_ACCOUNT_TOKEN) in your GitHub repository settings. This avoids hardcoding credentials in your workflow files.

GitLab CI

nctl-scan:
  image: ubuntu:latest
  variables:
    NIRMATA_SERVICE_ACCOUNT_TOKEN: $NIRMATA_SERVICE_ACCOUNT_TOKEN
  script:
    - curl -LO https://downloads.nirmata.io/nctl/stablereleases/nctl_linux_amd64.zip
    - unzip nctl_linux_amd64.zip && chmod u+x nctl && mv nctl /usr/local/bin/
    - nctl scan repository . --publish

Token Expiry

Service Account tokens may have an expiry depending on your NCH account configuration. When a token expires:

• For CLI usage, update the NIRMATA_SERVICE_ACCOUNT_TOKEN environment variable with a new token
• For CI/CD pipelines, update the secret in your pipeline configuration

To check or manage token expiry settings, navigate to Identity & Access → API Tokens in NCH.