Hinzufügen des Runners zu Ihrer CI-Pipeline

Die Analyse läuft in der CI-Pipeline, in der Ihr Code bereits liegt - Ihr Quellcode verlässt niemals Ihre Infrastruktur. In den folgenden Beispielen wird der Runner mit dem projektspezifischen Token aufgerufen.

Hinweis

Definieren Sie APPARCH_TOKEN als geheime/geschützte Variable in Ihrer CI. Wählen Sie das Runner-Image nach Sprache (z. B. collectors/dotnet, collectors/python, collectors/go).

Alle Beispiele beziehen das Image vom AppArch Hub; Details zu Authentifizierung, Sprachabgleich und häufigen Fehlern finden Sie dort.

GitHub Actions

.github/workflows/apparch.yml

name: AppArch
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # the target branch is then in the clone: the change's own files and its merge base
      - run: |
          echo "$APPARCH_INSTALLATION_KEY" | docker login hub.apparch.io -u "$APPARCH_INSTALLATION_ID" --password-stdin
          docker run --rm -v "$PWD:/workspace:ro" \
            -e APPARCH_Collector__Token="$APPARCH_TOKEN" \
            -e APPARCH_Collector__ApiUrl="https://api.yourdomain.com" \
            -e GITHUB_EVENT_NAME -e GITHUB_REF -e GITHUB_REPOSITORY \
            -e GITHUB_SERVER_URL -e GITHUB_BASE_REF -e GITHUB_SHA \
            hub.apparch.io/collectors/dotnet:latest /workspace
        env:
          APPARCH_TOKEN: ${{ secrets.APPARCH_TOKEN }}
          APPARCH_INSTALLATION_ID: ${{ secrets.APPARCH_INSTALLATION_ID }}
          APPARCH_INSTALLATION_KEY: ${{ secrets.APPARCH_INSTALLATION_KEY }}

GitLab CI

# Image pulls are authorized with your INSTALLATION credential, not the project token
# (Settings → CI/CD → Variables):
#   DOCKER_AUTH_CONFIG = {"auths":{"hub.apparch.io":{"auth":"base64(<installation-id>:<installation-key>)"}}}
archpilot:
  image: hub.apparch.io/collectors/dotnet:latest
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    APPARCH_Collector__Token: "$APPARCH_TOKEN"
    APPARCH_Collector__ApiUrl: "https://api.yourdomain.com"
  script:
    # Optional flags: --modules archpilot,archscan (pin what runs)
    #                 --fail-on critical (fail this step when findings at/above the level exist)
    - apparch "$CI_PROJECT_DIR"

Bitbucket Pipelines

pipelines:
  pull-requests:
    '**':
      - step:
          image:
            name: hub.apparch.io/collectors/dotnet:latest
            username: $APPARCH_INSTALLATION_ID
            password: $APPARCH_INSTALLATION_KEY
            run-as-user: 0   # the clone belongs to root; a PR run fetches the target branch into it
          script:
            - export APPARCH_Collector__Token="$APPARCH_TOKEN"
            - export APPARCH_Collector__ApiUrl="https://api.yourdomain.com"
            - apparch "$BITBUCKET_CLONE_DIR"

Azure DevOps

trigger: none
pr: ['*']
pool: { vmImage: ubuntu-latest }
steps:
  - checkout: self
    fetchDepth: 0   # the target branch is then in the clone: the change's own files and its merge base
  - script: |
      echo "$(APPARCH_INSTALLATION_KEY)" | docker login hub.apparch.io -u "$(APPARCH_INSTALLATION_ID)" --password-stdin
      docker run --rm -v "$(Build.SourcesDirectory):/workspace:ro" \
        -e APPARCH_Collector__Token="$(APPARCH_TOKEN)" \
        -e APPARCH_Collector__ApiUrl="https://api.yourdomain.com" \
        -e SYSTEM_PULLREQUEST_PULLREQUESTID="$(System.PullRequest.PullRequestId)" \
        -e SYSTEM_PULLREQUEST_TARGETBRANCH="$(System.PullRequest.TargetBranch)" \
        -e SYSTEM_TEAMPROJECT="$(System.TeamProject)" \
        -e BUILD_REPOSITORY_NAME="$(Build.Repository.Name)" \
        -e SYSTEM_COLLECTIONURI="$(System.CollectionUri)" \
        -e BUILD_SOURCEVERSION="$(Build.SourceVersion)" \
        hub.apparch.io/collectors/dotnet:latest /workspace

Jenkins

pipeline {
  agent { docker { image 'hub.apparch.io/collectors/dotnet:latest' registryUrl 'https://hub.apparch.io' registryCredentialsId 'apparch-hub' } }
  environment {
    APPARCH_Collector__Token = credentials('APPARCH_TOKEN')
    APPARCH_Collector__ApiUrl = 'https://api.yourdomain.com'
    // PR review (ArchPilot) needs the MR context set explicitly; without these the run is a full scan (ArchScan).
    APPARCH_Collector__Provider__Type = 'gitlab' // gitlab | github | bitbucket | azuredevops
    APPARCH_Collector__Provider__ProjectId = 'group/project'
    APPARCH_Collector__Provider__PullRequestId = "${env.CHANGE_ID}"
  }
  stages {
    stage('AppArch') {
      steps {
        sh 'apparch "$WORKSPACE"'
      }
    }
  }
}

Beim nächsten Mal, wenn ein PR/MR geöffnet wird, hinterlässt ArchPilot zeilenweise Kommentare. Der Runner wählt den Modus automatisch: In einer PR/MR-Pipeline läuft die schnelle Prüfung (ArchPilot), in einer Push-Pipeline der vollständige Scan (ArchScan).

Der Container-Benutzer

Die Collector-Images laufen mit einem Benutzer ohne Root-Rechte (uid 10001) und lesen den Checkout nur, auch wenn er einem anderen Benutzer gehört. In einem Pull Request vergleicht der Collector die Änderung mit ihrem Zielbranch (die eigenen Dateien der Änderung, ihre Merge-Basis); dieser Branch muss daher im Klon vorhanden sein:

• GitHub Actions und Azure DevOps: Die Beispiele checken die ganze Historie aus (fetch-depth: 0, fetchDepth: 0); der Zielbranch ist dann schon da, und nichts wird geschrieben.
• GitLab CI und Jenkins: funktionieren unverändert (GitLabs Klon ist für den Job beschreibbar, Jenkins startet den Container mit seinem eigenen Benutzer).
• Bitbucket Pipelines: Der Klon gehört immer root, und der Collector holt den Zielbranch hinein; das Beispiel führt den Schritt daher als root aus (run-as-user: 0).

Ohne das läuft der Schritt trotzdem durch, prüft aber alle Befunde statt nur die der Änderung und überspringt die Prüfungen, die mit dem Zielbranch vergleichen (entfernte Autorisierung, neuer Abhängigkeitszyklus). Besteht Ihr Runner an anderer Stelle auf Root, geben Sie es ausdrücklich an: docker run --user 0 ..., in Kubernetes securityContext.runAsUser: 0.

Selbstsignierte Zertifikate oder interne CAs

Wird Ihre AppArch-Installation mit einem Zertifikat ausgeliefert, dem der CI-Runner nicht traut - eine interne CA oder ein selbstsigniertes Zertifikat -, scheitert der Lauf beim Abruf des Regelkatalogs mit einem TLS-Fehler. Zwei Wege, in dieser Reihenfolge:

1. Die CA im Runner-Image als vertrauenswürdig hinterlegen. Das Zertifikat wird dann wie jedes andere geprüft und am Collector ändert sich nichts.
2. Die Prüfung mit SslVerify abschalten:

SslVerify=false                     # oder SSL_VERIFY, oder APPARCH_Collector__SslVerify

false, 0, no und off schalten sie ab; alles andere - auch leer - lässt sie an. Der .NET-Collector akzeptiert zusätzlich das Flag --no-ssl-verify. Jeder Lauf schreibt ssl verify on bzw. ssl verify OFF - server certificate not checked in seinen Boot-Block.

Achtung

Ohne Prüfung kann der Collector Ihre Api nicht von irgendetwas unterscheiden, das unter dieser Adresse antwortet: Projekt-Token und Findings gehen dann an wen auch immer zuhört. Nutzen Sie es, wenn das Vertrauen in die CA nicht möglich ist - nicht als Standard.