NOTE: This GitHub Action is for users of APIsec Standard, Professional, and Enterprise who are integrating scans into their GitHub workflows. If you are looking for the free utility by APIsec University- you can find that here

APIsec addresses the critical need to secure APIs before they reach production. APIsec provides the industry’s only automated and continuous API testing platform that uncovers security vulnerabilities and logic flaws in APIs. Clients rely on APIsec to evaluate every update and release, ensuring that no APIs go to production with vulnerabilities.

You develop the application and API, we bring complete and continuous security testing to you, accelerating development.

Know your API and Applications are secure with Apisec – our automated and continuous API security testing platform.

Apisec functions in the following simple steps.

Connect your API gateways, including Apigee, Kong, Mulesoft, AWS API Gateway, Azure API Gateway, etc. Or point us towards your API. Apisec instantly learns your live API composition, including the list of endpoints and operations, and creates an API functionality map. Apisec supports various API specifications, including OpenAPI specification, Swagger, Postman collection, RAML, etc.

Apisec automatically creates thousands of attack playbooks to comprehensively and completely test every function of your API. The playbooks address the entire OWASP API Security Top 10 and more, giving you complete coverage.

Apisec runs playbooks against your APIs to ensure the code check-in introduces no vulnerabilities. These playbooks are non-intrusive, save, and run against test/staging or production environments.

The Apisec playbooks are designed to find the trickiest vulnerabilities - business logic flaws, OWASP API top 10, and not just standard security issues.

You can view the scan results from the project home page in APIsec Platform. The link to view the scan results is also displayed on the console on successful completion of action.

APIsec also provides Summary Report with OWASP Coverage, Category wise Test Cases and Vulnerabilities count. This can be used to share summary information about the security quality of your application without exposing the details of potentially-exploitable findings.

If you configure the Issue Tracker to GitHub Issues (see Auto Bug Management), the list of open vulnerabilities across all security scans executed within this project can be viewed and closed from the GitHub issues.

Identified vulnerabilities are formatted into SARIF and then reported into the security tab in your GitHub repository if code scanning is enabled.

Sign up for a free account with Apisec https://cloud.apisec.ai/#/signup

Login into Apisec and Register API on the Apisec dashboard. For example, you can use this sample NetBank OpenAPI Specification URL: http://netbanking.apisec.ai:8080/v2/api-docs” and name your project NetBank

Go to your GitHub Repository on which you like to activate Apisec scanning. Make sure the GitHub Advanced Security is activated. Select the Security tab, then click on Set up code scanning, then search and select APIsec Scan action.

If you do not have GitHub Advanced Security enabled you can still add the apisec-run-scan action to existing GitHub workflow or create one. To create a new workflow select the Actions tab and click Configure Simple Workflow, then search and select APIsec Scan action from marketplace.

This will open the APIsec Scan action in the edit mode, now change the apisec-project property to your registered API name i.e. NetBank.

Now you need to add apisec_username and apisec_password as repository secrets. Go to Repository/Settings/Secrets/New repository secrets and use your free account credentials.

Go to the Actions tab, select APIsec action and click Run workflow. Once the action completes successfully, it will report vulnerabilities in the Security/Code scanning alerts. Click on one of the reported alerts to learn more about the vulnerability and remediation best practices.

Here is the video: https://drive.google.com/drive/folders/1x0fi8Cg2lUMM-TIlfxbS-xSSbF57zc4_?usp=sharing

Required The APIsec username with which the scans will be executed.

Note: You can create a new user on APIsec with 'ROLE_USER' privilege.

Required The Password of the APIsec user with which the scans will be executed.

Required The Name of the project for security scan.

Optional The Name of the scan profile to be executed.

Optional The location the scan will be executed in

Optional The name of the sarif format result file. The file is written only if this property is provided.

Optional To get notify with scans results.

Optional Pass the severity string for which pipeline execution breaks upon finding that severity vulnerability. Possible string values are Critical, High and Medium severity. By default its an empty string ""

Optional Set this value as "true" to register a project and trigger a scan.

Optional OpenAPI Spec Url for registering a project.

Optional To refresh playbooks of a project and trigger a scan.

Below is a sample of a complete workflow action. It does not have ALL the possible elements. Further down in the documentation you can see additional options for further configuration.

# This is a starter workflow to help you get started with APIsec-Scan Actions

name: APIsec

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the "main" branch
  # Customize trigger events based on your DevSecOps processes.
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
  schedule:
    - cron: '21 19 * * 4'

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:


permissions:
  contents: read

jobs:

  Trigger_APIsec_scan:
    permissions:
      security-events: write # for github/codeql-action/upload-sarif to upload SARIF results
      actions: read # only required for a private repository by github/codeql-action/upload-sarif to get the Action run status 
    runs-on: ubuntu-latest

    steps:
       - name: APIsec scan
         uses: apisec-inc/apisec-run-scan@v1.0.6
         with:
          # The APIsec username with which the scans will be executed
          apisec-username: ${{ secrets.apisec_username }}
          # The Password of the APIsec user with which the scans will be executed
          apisec-password: ${{ secrets.apisec_password}}
          # The name of the project for security scan
          apisec-project: "VAmPI"
          # The name of the sarif format result file The file is written only if this property is provided.
          sarif-result-file: "apisec-results.sarif"
       - name: Import results
         uses: github/codeql-action/upload-sarif@v2
         with:
          sarif_file: ./apisec-results.sarif

The APIsec credentials are read from github secrets.

Warning: Never store your secrets in the repository.

- name: Trigger APIsec scan
  id: scan
  uses: apisec-inc/apisec-run-scan@v1.0.6
  with:
    apisec-username: ${{ secrets.apisec_username }}
    apisec-password: ${{ secrets.apisec_password }}
    apisec-project: "VAmPI"

- name: Trigger APIsec scan
  id: scan
  uses: apisec-inc/apisec-run-scan@v1.0.6
  with:
    apisec-username: ${{ secrets.apisec_username }}
    apisec-password: ${{ secrets.apisec_password }}
    apisec-project: "VAmPI"
    apisec-profile: "Staging"
    apisec-region: "Super_1"

- name: Trigger APIsec scan
  id: scan
  uses: apisec-inc/apisec-run-scan@v1.0.6
  with:
    apisec-username: ${{ secrets.apisec_username }}
    apisec-password: ${{ secrets.apisec_password }}
    apisec-project: "VAmPI"
    sarif-result-file: "apisec-results.sarif"
    
- name: upload sarif file to repository
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: ./apisec-results.sarif

- name: Trigger APIsec scan
  id: scan
  uses: apisec-inc/apisec-run-scan@v1.0.6
  with:
    apisec-username: ${{ secrets.apisec_username }}
    apisec-password: ${{ secrets.apisec_password }}
    apisec-project: "VAmPI"
    apisec-email-report: "true"

- name: Trigger APIsec scan
  id: scan
  uses: apisec-inc/apisec-run-scan@v1.0.6
  with:
    apisec-username: ${{ secrets.apisec_username }}
    apisec-password: ${{ secrets.apisec_password }}
    apisec-project: "VAmPI"
    apisec-fail-on-vuln-severity: "High"

- name: Trigger APIsec scan
  id: scan
  uses: apisec-inc/apisec-run-scan@v1.0.6
  with:
    apisec-username: ${{ secrets.apisec_username }}
    apisec-password: ${{ secrets.apisec_password }}
    apisec-project: "VAmPI"
    apisec-oas: "true"
    apisec-openapi-spec-url: "http://netbanking.apisec.ai:8080/v2/api-docs"
        

- name: Trigger APIsec scan
  id: scan
  uses: apisec-inc/apisec-run-scan@v1.0.6
  with:
    apisec-username: ${{ secrets.apisec_username }}
    apisec-password: ${{ secrets.apisec_password }}
    apisec-project: "VAmPI"
    apisec-refresh-playbooks: "true"
        

   Script Purpose: This script does following things:
   
       1. Will register a project if one with the project name doesn't exist in APIsec product. 
          If it exists then script will either refresh the playbooks provided the user have  
          set the flag --refresh-playbooks as true or script will trigger scan on it.
                     
          User need to set --oas as true and --openApiSpecUrl with swagger/open api spec URL
          like --oas true --openApiSpecUrl "http://netbanking.apisec.ai:8080/v2/api-docs"

       2. Will refresh/regenerate playbooks of a project if --refresh-playbooks flag is set as true.

       3. Will trigger a scan on a project.

       4. Will generate Sarif file after scan trigger gets completed, if --outputfile parameter passed with some string like "sarif".
          We can use it to  file Vulnerabilities in Github CodeScanning/SecurityCenter.

       5. Checks for vulnerability  of a severity and breaks pipeline execution upon finding one for following use-cases.                    

             i) If user set flag   --fail-on-vuln-severity severity as Critical, then only Critical severity will be checked.

            ii) If user set flag  --fail-on-vuln-severity severity as High, then Critical and High severities will be checked.

           iii) If user set flag --fail-on-vuln-severity severity as Medium, then Critical, High and Medium severity will be checked.

       6. To get email reports for trigger scans we need to set --emailReport flag as "true".