pipeline integrations.md

Chaining GitHub Actions for Threagile Workflow

To chain additional GitHub Actions to the provided threagile_job, you can define dependent jobs or add steps within the same workflow.

1. Add a Dependent Job

Define a new job that depends on the threagile_job. Use the needs keyword to ensure the new job runs only after threagile_job completes.

jobs:
  threagile_job:
    runs-on: [ Linux ]
    name: Threat Model Analysis
    steps:
      # Your existing steps here...

  dependent_job:
    runs-on: [ Linux ]
    name: Post-Threagile Processing
    needs: threagile_job
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Use Threagile Artifacts
        run: |
          # Access the artifacts generated by threagile_job
          ls -la threagile/output
          echo "Processing stats.json and risks.json..."
          # Add your custom processing logic here

2. Add Steps to the Same Job

For lightweight tasks related to threat modeling, add additional steps to threagile_job.

jobs:
  threagile_job:
    runs-on: [ Linux ]
    name: Threat Model Analysis
    steps:
      # Your existing steps here...

      # Process the JSON artifacts
      - name: Process JSON Artifacts
        run: |
          echo "Processing JSON artifacts..."
          jq '.' threagile/output/stats.json > processed_stats.json
          jq '.' threagile/output/risks.json > processed_risks.json

      # Upload processed files
      - name: Upload Processed Files
        uses: actions/upload-artifact@v3
        with:
          name: processed-json
          path: processed_stats.json,processed_risks.json

3. Trigger Additional Workflows

Use a repository dispatch event to trigger another workflow after the threagile_job completes. This is useful for decoupled workflows.

Step in threagile_job to Trigger a Dispatch:

- name: Trigger Follow-up Workflow
  run: |
    curl -X POST -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
         -d '{"event_type": "post-threagile"}' \
         https://api.github.com/repos/${{ github.repository }}/dispatches

New Workflow Listening for Dispatch:

name: Post-Threagile Workflow

on:
  repository_dispatch:
    types: [post-threagile]

jobs:
  post_processing_job:
    runs-on: [ Linux ]
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Process Artifacts
        run: |
          # Add your custom processing logic here

4. Prerequisites

• Ensure the threagile.yaml file is included in your repository and properly configured.
• The repository must have the actions/checkout step for accessing files.
• GitHub Actions must have permission to push changes (if applicable).
• Install jq or equivalent JSON processing tool for artifact manipulation (if needed).

5. Environment Variables and Secrets

The following environment variables and secrets are required for the pipeline:

• GITHUB_TOKEN: Required for pushing updates and triggering workflows.

You can set these secrets in your repository settings under Settings > Secrets and variables > Actions.

6. Pipeline Overview

1. Checkout Repository: Ensures the repository is available in the action.
2. Run Threagile: Processes the threagile.yaml file to generate reports and artifacts.
3. Verify Artifacts: Checks and lists the generated files for integrity.
4. Archive Artifacts: Saves output files for later reference or download.
5. Commit and Push Changes: Updates the repository with new reports and diagrams (if applicable).
6. Trigger Additional Workflows: Initiates dependent workflows for further processing.

7. Common Errors and Troubleshooting

• Error: Missing threagile.yaml File Ensure the file exists in the repository root and is correctly formatted.
• Error: Permission Denied Check that the GitHub token has write permissions for the repository.
• Error: JSON Processing Failed Verify that the jq tool is installed and the JSON files are correctly formatted.

8. Customization Options

• Change Output Paths: Modify the model-file or path in the action to fit your repository structure.
• Add Notifications: Use a GitHub Action like slackapi/slack-github-action to send notifications.
• Integrate Additional Checks: Add security scans or vulnerability checks to enhance the pipeline.

9. Example Scenarios

• Send Threagile Reports via Email Use a GitHub Action like dawidd6/action-send-mail to email reports to stakeholders.
• Integrate with CI/CD Pipelines Use Threagile in combination with CI/CD tools like Jenkins or GitLab CI to analyze threat models in build pipelines.

10. References and Links

• Threagile Documentation
• GitHub Actions Documentation
• jq JSON Processor

Summary

• Dependent Job: Use needs to define dependencies between jobs.
• Additional Steps: Add extra steps within the same job for lightweight tasks.
• Separate Workflow: Use repository_dispatch to trigger separate workflows for more complex processing.

Choose the approach that best fits your requirements!