• Supported frameworks
• When does API Discovery run?
• Example API Discovery configurations
• Java Spring-Boot
  • Supported Applications
  • Configure as pipeline job
    • Image requirements
  • Available CI/CD variables
• Get support or request an improvement

API Discovery

API Discovery analyzes your application and produces an OpenAPI document describing the web APIs it exposes. This schema document can then be used by the API security testing analyzer or API Fuzzing to perform security scans of the web API.

Supported frameworks

• Java Spring-Boot

When does API Discovery run?

API Discovery runs as a standalone job in your pipeline. The resulting OpenAPI document is captured as a job artifact so it can be used by other jobs in later stages.

API Discovery runs in the test stage by default. The test stage was chosen as it typically executes before the stages used by other security features such as API security testing and API fuzzing.

Example API Discovery configurations

The following projects demonstrate API Discovery:

• Example Java Spring Boot v2 Pet Store

Java Spring-Boot

Spring Boot is a popular framework for creating stand-alone, production-grade Spring-based applications.

Supported Applications

• Spring Boot: v2.X (>= 2.1)
• Java: 11, 17 (LTS versions)
• Executable JARs

API Discovery supports Spring Boot major version 2, minor versions 1 and later. Versions 2.0.X are not supported due to known bugs which affect API Discovery and were fixed in 2.1.

Major version 3 is planned to be supported in the future. Support for major version 1 is not planned.

API Discovery is tested with and officially supports LTS versions of the Java runtime. Other versions may work also, and bug reports from non-LTS versions are welcome.

Only applications that are built as Spring Boot executable JARs are supported.

Configure as pipeline job

The easiest way to run API Discovery is through a pipeline job based on our CI template. When running in this method, you provide a container image that has the required dependencies installed (such as an appropriate Java runtime). See Image Requirements for more information.

1. A container image that meets the image requirements is uploaded to a container registry. If the container registry requires authentication see this help section.
2. In a job in the build stage, build your application and configure the resulting Spring Boot executable JAR as a job artifact.

3. Include the API Discovery template in your .gitlab-ci.yml file.

   include:
      - template: Security/API-Discovery.gitlab-ci.yml
   

   Only a single include statement is allowed per .gitlab-ci.yml file. If you are including other files, combine them into a single include statement.

   include:
      - template: Security/API-Discovery.gitlab-ci.yml
      - template: Security/DAST-API.gitlab-ci.yml
   

4. Create a new job that extends from .api_discovery_java_spring_boot. The default stage is test which can be optionally changed to any value.

   api_discovery:
       extends: .api_discovery_java_spring_boot
   

5. Configure the image for the job.

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: openjdk:11-jre-slim
   

6. Provide the Java class path needed by your application. This includes your compatible build artifact from step 2, along with any additional dependencies. For this example, the build artifact is build/libs/spring-boot-app-0.0.0.jar and contains all needed dependencies. The variable API_DISCOVERY_JAVA_CLASSPATH is used to provide the class path.

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: openjdk:11-jre-slim
       variables:
           API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
   

7. Optional. If the image provided is missing a dependency needed by API Discovery, it can be added using a before_script. In this example, the openjdk:11-jre-slim container doesn’t include curl which is required by API Discovery. The dependency can be installed using the Debian package manager apt:

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: openjdk:11-jre-slim
       variables:
           API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
       before_script:
           - apt-get update && apt-get install -y curl
   

8. Optional. If the image provided doesn’t automatically set the JAVA_HOME environment variable, or include java in the path, the API_DISCOVERY_JAVA_HOME variable can be used.

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: openjdk:11-jre-slim
       variables:
           API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
           API_DISCOVERY_JAVA_HOME: /opt/java
   

9. Optional. If the package registry at API_DISCOVERY_PACKAGES is not public, provide a token that has read access to the GitLab API and registry using the API_DISCOVERY_PACKAGE_TOKEN variable. This is not required if you are using gitlab.com and have not customized the API_DISCOVERY_PACKAGES variable. The following example uses a custom CI/CD variable named GITLAB_READ_TOKEN to store the token.

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: openjdk:8-jre-alpine
       variables:
           API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
           API_DISCOVERY_PACKAGE_TOKEN: $GITLAB_READ_TOKEN
   

After the API Discovery job has successfully run, the OpenAPI document is available as a job artifact called gl-api-discovery-openapi.json.

Image requirements

• Linux container image.
• Java versions 11 or 17 are officially supported, but other versions are likely compatible as well.
• The curl command.
• A shell at /bin/sh (like busybox, sh, or bash).

Available CI/CD variables

Get support or request an improvement

To get support for your particular problem, use the getting help channels.

The GitLab issue tracker on GitLab.com is the right place for bugs and feature proposals about API Discovery. Use ~"Category:API Security" label when opening a new issue regarding API Discovery to ensure it is quickly reviewed by the right people. Refer to our review response SLO to understand when you should receive a response.

Search the issue tracker for similar entries before submitting your own, there’s a good chance somebody else had the same issue or feature proposal. Show your support with an emoji reaction or join the discussion.

When experiencing a behavior not working as expected, consider providing contextual information:

• GitLab version if using a self-managed instance.
• .gitlab-ci.yml job definition.
• Full job console output.
• Framework in use with version (for example Spring Boot v2.3.2).
• Language runtime with version (for example OpenJDK v17.0.1).