Key Concepts and Terminology
The following terminologies help you get started with Application Dependency Management (ADM). The Oracle Cloud Infrastructure documentation (OCI) provides related terminology.
- Application Dependency
-
A software component represented by a package URL (purl) or GAV (Maven Group, Artifact, Version coordinate) that must be checked for vulnerabilities within a vulnerability audit.
- Artifact
-
An artifact is a library such as a jar that's either produced or used by a software project.
A software project's dependencies are specified in terms of its artifacts. Some artifacts are produced because of the project's continuous integration process. They're located in the project's repository. Other artifacts can be downloaded from third-party repositories and, in turn, have dependent artifacts. Therefore, a project has a graph of dependencies, some that are created by the project itself, and others provided by external contributors.
- Continuous Integration Tool
-
Continuous integration is a practice where members of a development team share and merge their changes into a unified version control repository. The practice is used with automated tests, and other verification measures, to ensure the quality of the unified version.
A continuous integration tool automates this practice, and provides a framework in which the tests and verification measures are performed. Access to a tool is often controlled through permissions where you can grant read and write access to team members, collaborators, or other stakeholders.
Application Development Management supports the following continuous integration tools:- OCI DevOps Build Pipelines
- GitHub Actions
- GitLab Pipeline
- Jenkins Pipeline
- Knowledge Base
-
A knowledge base provides access to the ADM services vulnerabilities. When you configure a remediation recipe or create a vulnerability audit, a knowledge base must be specified with which it's associated. The ADM knowledge base stores details of software dependencies for various programming languages and their vulnerabilities. The knowledge base is enhanced to store the class and method details of some Java vulnerabilities.
- Pull Request
-
A pull request, also known as a merge request, is a common means of contributing to a source code repository that uses a distributed version control system, such as those compatible with ADM.
For example, a user creates a pull request to tell others about the changes that have been pushed to a branch in a repository. When used with a continuous integration tool, the pull request causes the tool to build the project and verify it by using tests. If the verification is successful, the changes are merged with the existing project source code.
- Remediation Recipe
-
A remediation recipe represents the configuration for a workflow, consisting of a sequence of four Stages:
- Detect
- Recommend
- Verify
- Apply
Typically, you create a remediation recipe corresponding to the monitored branch of the Repository that contains the project.
A Remediation Recipe has a status, which must be one of:
- Active
- Creating
- Deleted
- Deleting
- Failed
- Inactive
- Needs Attention
- Updating
- Remediation Run
-
A remediation run describes the action of performing a remediation recipe, in which each of the remediation recipe's stages are performed in sequence until a completed stage is reached. You can trigger a remediation run manually, or specify that a remediation run is triggered when a new vulnerability is identified.
A remediation recipe can be run only if it's in its active status.
A remediation run has a status, which must be one of:
- Accepted
- Canceled
- Canceling
- Created
- Failed
- In Progress
- Succeeded
ADM supports a single run at a time for a recipe.
- Repository
-
A code repository is a storage location for the software project. It typically includes the project's source code, project metadata and other artifacts on which the project depends. Access to a repository is often controlled through permissions where you can grant read and write access to team members, collaborators, or other stakeholders.
Application Development Management supports the following repositories:
- OCI DevOps
- GitHub
- GitLab
- Secret
-
A secret is a credential such as a password, certificate, SSH key, or authentication token that you use with OCI services.
- Severity
-
Severity refers to the impact or criticality of a vulnerability, represented by different values.
- Stage
-
A Stage describes a step in a remediation run. The four stages are:
- Detect: Detect vulnerabilities in the application. A remediation run proceeds to the next stage of a remediation run if one or more vulnerabilities are detected that exceed the configured CVE score threshold. If none then the remediation run is complete, and you can see the output of the vulnerability audit.
- Recommend: Identify the recommended third-party dependencies that the application use and opens a Pull Request to propose these changes. If successful, the remediation run proceeds to the next stage. If it can't resolve new dependency versions to address the vulnerabilities the remediation run ends here providing the details of what it can recommend and the vulnerabilities it couldn't resolve. If the stage fails, then the remediation run ends here in a failed state.
- Verify: Verify the changes using the tests you specified in the continuous integration tool. The remediation run proceeds to the next stage if the tests succeed.
- Apply: Merge the pull request. If the merge fails, the remediation run ends in a failed state.
A Stage has a status, which must be one of:
- Canceled
- Created
- Failed
- In Progress
- Succeeded
- Vault
-
A vault is a logical entity where the OCI Vault service creates and durably stores keys and Secrets.
- Vulnerability
- A vulnerability is a weakness or error in a project artifact, such as an application dependency. A vulnerability is a generalization of an information security flaw, such as those described by the Common Vulnerabilities and Exposures (CVE) system.
The National Vulnerability Database (NVD) provides a measure of the severity of a software vulnerability, using the Common Vulnerability Scoring System (CVSS), ranging from 0 to 10. The NVD supports both CVSS v2.0 and v3.0 standards. For more information about vulnerability metrics, see National Vulnerability Database. Along with CVSS, ADM provides its own severity indicators such as High, Medium and Low. Vulnerabilities with Unknown severity aren't included in vulnerability audits.
A false-positive vulnerability refers to a vulnerability that's detected during the vulnerability audit creation but isn't considered affecting the application according to the dependency details. The false positive is identified using the Oracle GraalVM native image build that captures the application's actual usage in the code through the application's classes and methods, and then compares it against the Application Dependency Management's knowledge base.
An ignored vulnerability refers to a vulnerability that's detected during the vulnerability audit creation but is marked as ignored based on the configuration. The configuration is set up to ignore vulnerabilities based on exclusion patterns or maximum permissible severity values.
- Vulnerability Audit
- A vulnerability audit contains the vulnerabilities that an application is affected by because of its dependencies at a specific point in time. It includes summary information on the quantities and maximum severity of the vulnerabilities.
A vulnerability audit is associated with a knowledge base.
- Vulnerability Audit Usage Data
- Vulnerability audit creation can optionally accept usage data as an input when creating a vulnerability audit. The usage data details all the classes and methods used in the GraalVM native-image created from the Java application. The ADM service uses this data to identify false-positive vulnerabilities where the application might not be vulnerable because of the application dependency's vulnerable code not being used. The usage data is uploaded as a gzip file to the OCI Object Storage in JSON format. The data is generated by the GraalVM Native Image and the Native Image inspection tool.