Overview

This document describes the operation of the Secure Code Warrior Trust Agent with the purpose of assisting the completion of risk and security reviews. A core part of the SCW Trust Agent functionality is integration with Git-based source code management (SCM) tools such as GitHub, GitLab and Bitbucket. The Trust Agent provides improved visibility into the application security posture of an organization by bridging the gap between application security training and developer code commits.

• On-Premises
• GitHub APP
• Manual Upload
• Data Flows 

High Level Design

The SCW Trust Agent can connect with your Git SCM environment via a variety of methods depending on your organization-specific environment and policies. 

On-Premises

This method involves running a container within your environment that is wholly configured and managed by your team. The container image is published at:

• ghcr.io/securecodewarrior/trust-agent:latest

Using this container approach allows for connecting to both cloud-based and on-premises source code management platforms and the on-premises container can be run at a frequency of your choosing.

The container image includes a command line application that automatically runs and is configured via environment variables passed to the container. This includes all secrets, tokens and keys required for accessing your Git repositories as well as an API key for connecting to the Trust Agent API. The command line application will clone the configured repositories locally within the container, then process and summarise the commit data before automatically pushing the summarised data to the Trust Agent API and terminating. At no point does your organization’s source code, or keys to access your organization’s source code, leave your environment under this approach.

GitHub App

This approach is specific to organizations that use GitHub Cloud or GitHub Enterprise Cloud as their source code management tool. It involves a GitHub App that is installed into your GitHub organization. GitHub on-premises environments do not support installation of published GitHub Apps and will need to use an alternative method.

This GitHub App requires the following permissions:

• Read-Only - Repository Contents
  Used to read repository commits in order to store a summarised form in the Trust Agent for correlation against developer training progress
• Read-Only - Organization Members
  Used to verify organization membership and to read organization-approved email addresses for commit authors to enable matching of GitHub developer identities against Secure Code Warrior learner identities
• Read-Only - Repository Metadata
  Mandatory access required for all GitHub Apps to search repositories and access repository metadata

In line with standard GitHub App installation configuration, you can select specific repositories to install it for, or install it for all repositories.

Once installed, an additional OAuth login is required to prove GitHub organization membership before the organization can be connected to a Secure Code Warrior company entity by a company administrator user. Once a GitHub organization is connected, the Trust Agent will be available to all company administrator users within the Secure Code Warrior company.

The Trust Agent will retrieve and update commit data every 6 hours via the GitHub API.

Manual Upload

A manual “offline” approach utilising the vendor-agnostic Git command line is also provided in order to support trials and proof-of-concepts of the Trust Agent without needing to integrate directly with your Git environment, which typically entails a number of approvals to be sought. At no point does your organization’s source code, or keys to access your organization’s source code, leave your environment under this approach.

The Git command line approach is simple and will work with any Git repository that can be cloned locally on a *nix system, regardless of the Git vendor. A shell script is provided that will process the commits for all repositories within a directory and output a summarised version to individual YAML files (one per identified repository). These YAML files can then be inspected manually prior to uploading into the Trust Agent to populate commit data. Please see the Data Flows section below for detailed information on the exact data that is captured in the YAML files.

Data Flows

Ingress to Trust Agent

The following data flows from your Git environment to the Trust Agent:

• Summarised commit data
  • Commit hash for uniquely identifying individual commits
  • Commit author name for display purposes
  • Commit author email address for matching Git environment identities against Secure Code Warrior learner identities
  • Commit timestamp for determining whether the configured training had been completed at the time of the code commit
  • List of modified file extensions and/or associated programming languages for determining whether the configured training had been completed in the appropriate language
• [On-Premises only] Secure Code Warrrior API key to authenticate to the Trust Agent API endpoint for automated push of summarised commit data
• [GitHub App only] OAuth tokens and data
  • Tokens for enabling access to GitHub APIs to fetch summarised commit data
  • Organization or group information to verify membership
• [GitHub App only] Mapping of GitHub logins to organization email addresses for more robust matching of Git environment identities against Secure Code Warrior learner identities

All data flows use the industry standard HTTPS (TLS) protocol for authentication, encryption and integrity.

Egress from Trust Agent

Currently, no data flows from the Trust Agent to your Git environment apart from the required communications to complete the OAuth flow (GitHub only), and API or Git clone requests.

Data persisted

The following data is persisted by the Trust Agent and protected with industry standard AES-256 encryption to enable the processing and display of commit insights for your Git repositories:

• Commit hash
• Commit author name
• Commit author email
  • [GitHub App only] Where available, the organization-approved email address is used instead of the email address recorded against the commit itself
• Commit timestamp
• List of modified file extensions and/or associated programming languages

The following data is persisted as part of the regular operation of the Trust Agent:

• Application logs for error troubleshooting
• Product analytics