The intersection of Infrastructure as Code (IaC) and continuous integration pipelines demands robust, automated security scanning. tfsec, a static analysis security scanner for Terraform code, has established itself as a critical component in modern DevSecOps workflows. Since October 2020, when the Thoughtworks Tech Radar promoted tfsec to Trial status, the tool has undergone significant evolution, including performance improvements, parsing rewrites, and the expansion of its feature set. A pivotal development in this trajectory is the integration of tfsec into GitHub Actions, enabling teams to automate security checks directly within their pull request workflows. This integration transforms security from a manual review step into an automated gatekeeper, ensuring that infrastructure definitions adhere to security best practices before they are merged.
Standard Security Scanning with tfsec-action
The foundational approach to integrating tfsec into a GitHub repository is through the tfsec-action. This action allows organizations to run security scans on every push to a main branch or on every pull request, ensuring that code is vetted for vulnerabilities before deployment. To implement this, developers create a workflow file, typically named tfsec.yml, within the .github/workflows directory at the root of the project.
The basic workflow structure defines a job that runs on the latest Ubuntu runner. The process begins by cloning the repository using the standard actions/checkout action. Once the code is available in the runner, the tfsec-action executes, scanning the codebase for security misconfigurations.
yaml
name: tfsec
on:
push:
branches:
- main
pull_request:
jobs:
tfsec:
name: tfsec
runs-on: ubuntu-latest
steps:
- name: Clone repo
uses: actions/checkout@master
- name: tfsec
uses: aquasecurity/[email protected]
While the basic configuration suffices for simple repositories, production environments often require more granular control. The tfsec-action supports a variety of optional inputs defined in the with: block of the workflow. These inputs allow teams to tailor the scanning behavior to their specific needs.
The working_directory input specifies the directory to scan, defaulting to the current working directory (.). This is particularly useful for monorepos where Terraform configurations are stored in subdirectories. The version input allows teams to pin the scanner to a specific release, ensuring consistent results across runs, though it defaults to the latest version if unspecified. Output formatting is another critical aspect; the format input allows users to override the default output to one of several structured formats, including JSON, CSV, Checkstyle, JUnit, or SARIF. This flexibility enables integration with various reporting tools and dashboards.
For scenarios where a failing security check should not block the build pipeline—such as during initial adoption or when dealing with known false positives—the soft_fail input can be set to true. This configuration allows the action to report failures without breaking the build, providing visibility without halting development. Additionally, the additional_args input permits the passing of any other arguments supported by the tfsec CLI, offering maximum flexibility for advanced use cases. To avoid rate-limiting issues when interacting with GitHub APIs, the github_token input can be utilized to authenticate API calls.
Enhancing Visibility with SARIF and Security Alerts
Beyond simple pass/fail build statuses, GitHub provides a dedicated Security tab for viewing alerts. tfsec can enrich this interface by annotating the exact areas in the codebase where security issues are found, providing details on the failure and its severity. This is achieved through the SARIF (Static Analysis Results Interchange Format) integration.
The SARIF workflow uses a specialized action, tfsec-sarif-action, which generates a SARIF report from the tfsec scan. This report is then uploaded to GitHub using the github/codeql-action/upload-sarif action. This integration updates the Security tab, allowing developers and reviewers to navigate directly to the problematic code segments within the GitHub UI.
yaml
name: tfsec
on:
push:
branches:
- main
pull_request:
jobs:
tfsec:
name: tfsec sarif report
runs-on: ubuntu-latest
steps:
- name: Clone repo
uses: actions/checkout@master
- name: tfsec
uses: tfsec/tfsec-sarif-action@main
with:
sarif_file: tfsec.sarif
- name: Upload SARIF file
uses: github/codeql-action/upload-sarif@v1
with:
sarif_file: tfsec.sarif
This process involves starting a new Ubuntu container, checking out the code for the relevant pull request or push, and processing the local path to generate the SARIF report. Once uploaded, the Security tab is updated with the identified checks, providing a centralized view of security posture that persists across commits and merges.
Inline Feedback with the tfsec PR Commenter
While the standard action and SARIF upload provide valuable information, they do not always offer immediate, contextual feedback to the developer within the pull request thread. The tfsec-pr-commenter-action addresses this by adding comments directly to the pull request where tfsec checks have failed. This approach facilitates quicker remediation by highlighting issues in the context of the code being reviewed.
To implement this, a workflow file such as tfsec_pr_commenter.yml is added to the .github/workflows directory. The workflow triggers on pull requests and requires specific permissions to write to the pull request comments. The GITHUB_TOKEN injected into the workflow must have permissions to write on pull requests, which is configured via a permissions block in the workflow definition.
yaml
name: tfsec-pr-commenter
on:
pull_request:
jobs:
tfsec:
name: tfsec PR commenter
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- name: Clone repo
uses: actions/checkout@master
- name: tfsec
uses: aquasecurity/[email protected]
with:
github_token: ${{ github.token }}
When a pull request is committed or reopened, the GitHub Action runs and adds comments where tfsec has failed. The comment is added only once per transgression, preventing spamming of the pull request with duplicate messages. The nature of the comment depends on the scope of the error. If an entire resource block is missing a critical definition, the error may span the entire block. However, if the issue is specific to a single attribute, such as an incorrect value, the comment is scoped to that specific line, providing precise guidance for the developer.
Consider a scenario where a developer adds an AWS S3 bucket to the codebase. If the bucket definition includes logging but fails to set up encryption, it will fail the tfsec check AWS017. The PR commenter action will detect this failure and add a comment to the pull request, alerting the reviewer and the developer to the missing encryption configuration. This immediate feedback loop allows reviewers to quickly identify issues and act accordingly, reducing the time to remediation.
The tfsec-pr-commenter-action also supports several optional inputs to customize its behavior. The working_directory defaults to the current working directory but can be specified to scan specific folders. The tfsec_version allows pinning the scanner version, while tfsec_args and tfsec_formats allow for the passing of additional arguments and output formats, respectively. The commenter_version can be pinned to a specific release. Finally, the soft_fail_commenter option can be set to true to allow the action to comment silently without breaking the build, providing a non-blocking feedback mechanism.
Conclusion
The integration of tfsec into GitHub Actions represents a significant advancement in the automation of infrastructure security. By leveraging the standard tfsec-action, teams can enforce basic security gates in their CI/CD pipelines. The SARIF integration enhances visibility by feeding data directly into GitHub's Security tab, providing a historical and centralized view of vulnerabilities. Meanwhile, the tfsec-pr-commenter-action bridges the gap between automated scanning and human review, offering contextual, inline feedback that accelerates the remediation process. Together, these tools form a comprehensive security automation strategy that aligns with modern DevSecOps principles, ensuring that infrastructure code is not only functional but also secure from the moment it is written. As tfsec continues to evolve, its deep integration with GitHub Actions ensures that security remains an integral, automated part of the development lifecycle.