[PPSC-579] docs(auth): establish JWT as primary authentication method (#99)

Update all CLI documentation to position JWT authentication
(client_id/client_secret) as the recommended first-class method,
with Basic auth (API token/tenant ID) as legacy fallback.

- Lead Quick Start and auth sections with JWT examples
- Reference VIPR External API screen for obtaining credentials
- Update all CI platform examples to use JWT env vars
- Add "Recommended"/"Legacy" labels throughout
- Note that tenant ID is auto-extracted from JWT token
- Fix pre-existing yamllint issues (document-start, indentation)
- Fix markdownlint MD036 (use headings instead of bold emphasis)

Author: yiftach-armis

README.md

@@ -216,6 +216,19 @@ cyclonedx-cli validate --input-file armis-cli-linux-amd64.tar.gz.sbom.cdx.json
 
 ### Set up authentication
 
+#### JWT Authentication (Recommended)
+
+Obtain client credentials from the VIPR external API screen in the Armis platform.
+
+```bash
+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)
+
 ```bash
 export ARMIS_API_TOKEN="your-api-token"
 export ARMIS_TENANT_ID="your-tenant-id"
@@ -242,8 +255,11 @@ armis-cli scan image nginx:latest
 #### Authentication Flags
 
 ```text
---token string          API token for authentication (env: ARMIS_API_TOKEN)
---tenant-id string      Tenant identifier (env: ARMIS_TENANT_ID)
+--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
@@ -266,38 +282,38 @@ armis-cli scan image nginx:latest
 Scans a local directory, creates a tarball, and uploads to Armis Cloud for analysis.
 
 ```bash
-armis-cli scan repo [path] --tenant-id [tenant-id]
+armis-cli scan repo [path]
 ```
 
 **Size Limit**: 2GB
 **Example**:
 
 ```bash
-armis-cli scan repo ./my-app --tenant-id my-tenant --format json --fail-on HIGH,CRITICAL
+armis-cli scan repo ./my-app --format json --fail-on HIGH,CRITICAL
 
 # Generate SBOM and VEX documents
-armis-cli scan repo ./my-app --tenant-id my-tenant --sbom --vex
+armis-cli scan repo ./my-app --sbom --vex
 ```
 
 ### Scan Container Image
 
 Scans a container image (local or remote) or a tarball.
 
 ```bash
-armis-cli scan image [image-name] --tenant-id [tenant-id]
-armis-cli scan image --tarball [path-to-tarball] --tenant-id [tenant-id]
+armis-cli scan image [image-name]
+armis-cli scan image --tarball [path-to-tarball]
 ```
 
 **Size Limit**: 5GB
 **Examples**:
 
 ```bash
 # Scan remote image
-armis-cli scan image nginx:latest --tenant-id my-tenant
+armis-cli scan image nginx:latest
 # Scan local image
-armis-cli scan image my-app:v1.0.0 --tenant-id my-tenant
+armis-cli scan image my-app:v1.0.0
 # Scan tarball
-armis-cli scan image --tarball ./image.tar --tenant-id my-tenant
+armis-cli scan image --tarball ./image.tar
 ```
 
 #### Pull Policy
@@ -400,8 +416,10 @@ jobs:
 
 **Required secrets:**
 
-- `api-token`: Armis API token for authentication
-- `tenant-id`: Tenant identifier for Armis Cloud
+- `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](#option-3-manual-installation) below).
 
 #### Option 2: GitHub Action
 
@@ -452,10 +470,10 @@ jobs:
           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 }}
+          ARMIS_CLIENT_ID: ${{ secrets.ARMIS_CLIENT_ID }}
+          ARMIS_CLIENT_SECRET: ${{ secrets.ARMIS_CLIENT_SECRET }}
         run: |
           armis-cli scan repo . \
-            --tenant-id "${{ secrets.ARMIS_TENANT_ID }}" \
             --format sarif \
             --fail-on HIGH,CRITICAL \
             > results.sarif
@@ -475,10 +493,10 @@ security-scan:
     - 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 . --tenant-id "$ARMIS_TENANT_ID" --format json --fail-on CRITICAL
+    - armis-cli scan repo . --format json --fail-on CRITICAL
   variables:
-    ARMIS_API_TOKEN: $ARMIS_API_TOKEN
-    ARMIS_TENANT_ID: $ARMIS_TENANT_ID
+    ARMIS_CLIENT_ID: $ARMIS_CLIENT_ID
+    ARMIS_CLIENT_SECRET: $ARMIS_CLIENT_SECRET
 ```
 
 ### Jenkins
@@ -487,15 +505,15 @@ security-scan:
 pipeline {
     agent any
     environment {
-        ARMIS_API_TOKEN = credentials('armis-api-token')
-        ARMIS_TENANT_ID = credentials('armis-tenant-id')
+        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 . --tenant-id "$ARMIS_TENANT_ID" --format junit > scan-results.xml
+                    armis-cli scan repo . --format junit > scan-results.xml
                 '''
                 junit 'scan-results.xml'
             }
@@ -516,9 +534,10 @@ steps:
     curl -sSL https://raw.githubusercontent.com/ArmisSecurity/armis-cli/main/scripts/install.sh | bash
   displayName: 'Install Armis CLI'
 - script: |
-    armis-cli scan repo . --tenant-id "$(ARMIS_TENANT_ID)" --format junit > $(Build.ArtifactStagingDirectory)/scan-results.xml
+    armis-cli scan repo . --format junit > $(Build.ArtifactStagingDirectory)/scan-results.xml
   env:
-    ARMIS_API_TOKEN: $(ARMIS_API_TOKEN)
+    ARMIS_CLIENT_ID: $(ARMIS_CLIENT_ID)
+    ARMIS_CLIENT_SECRET: $(ARMIS_CLIENT_SECRET)
   displayName: 'Run Security Scan'
 - task: PublishTestResults@2
   inputs:
@@ -543,7 +562,7 @@ jobs:
       - run:
           name: Run Security Scan
           command: |
-            armis-cli scan repo . --tenant-id "$ARMIS_TENANT_ID" --format json --fail-on HIGH,CRITICAL
+            armis-cli scan repo . --format json --fail-on HIGH,CRITICAL
 workflows:
   version: 2
   scan:
@@ -563,19 +582,29 @@ pipelines:
         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 . --tenant-id "$ARMIS_TENANT_ID" --format json --fail-on CRITICAL
+          - armis-cli scan repo . --format json --fail-on CRITICAL
 ```
 
 ---
 
 ## Environment Variables
 
-**Authentication:**
+**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 authentication |
-| `ARMIS_TENANT_ID` | Tenant identifier |
+| `ARMIS_API_TOKEN` | API token for Basic authentication |
+| `ARMIS_TENANT_ID` | Tenant identifier (required only with Basic auth) |
 
 **General:**
 
@@ -592,8 +621,9 @@ pipelines:
   - Repositories: 2GB
   - Container Images: 5GB
 - **Authentication Security**:
-  - API tokens should be stored securely and never committed to version control
-  - Rotate tokens periodically
+  - 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