Vanir: Missing Patch Scanner

Vanir is a source code-based static analysis tool that automatically identifies the list of missing security patches in the target system. By default, Vanir pulls up-to-date CVEs from Open Source Vulnerabilities (OSV) together with their corresponding signatures so that users can transparently scan missing patches for an up-to-date list of CVEs. Vanir currently supports C/C++ and Java source code, and Google-supplied Vanir signatures cover CVEs published through Android security bulletins since 2020 July. Vanir is primarily designed to detect missing security patches with low false-positive rate in a sustainable and scalable way.

---

Quick Start

Install Vanir as a package using pip

1. Install Vanir.

   pip install vanir
   

2. To scan your Android repo project located at ~/my/android/repo, run:

   python -m vanir.detector_runner repo_scanner Android ~/my/android/repo
   

3. Find the missing patches identified by Vanir at /tmp/vanir/report-YYYYMMDDhhmmss.html and /tmp/vanir/report-YYYYMMDDhhmmss.json.

Alternatively, follow the steps below to use the version from GitHub.

Clone Vanir from GitHub

[!CAUTION] This instruction is written based on systems using Bazel >= 8. For Bazel 7.1 and 7.0, edit .bazelrc to enable workspace and disable bzlmod. For Bazel 6, remove or comment out the line common --enable_workspace=False as this flag is not supported.

1. Install the following prerequisite tools in a Linux machine if not already installed:

   • Bazel

   • Git

     sudo apt install git
     

   • JRE >= Java 11

     sudo apt install openjdk-11-jre
     

2. Download Vanir and move to the Vanir directory.

3. To scan your Android repo project located at ~/my/android/repo, run:

   bazel build //:detector_runner
   ./bazel-bin/detector_runner repo_scanner Android ~/my/android/repo
   

4. Find the missing patches identified by Vanir at /tmp/vanir/report-YYYYMMDDhhmmss.html and /tmp/vanir/report-YYYYMMDDhhmmss.json

For further details, please see the User Guide section.

---

User Benefits

Code Variance Tolerance: Vanir identifies missing security patches from the customized ones. This can be especially beneficial for downstream branch maintainers (such as Android device vendors and custom kernel maintainers) who usually need to make additional changes on the upstream code for adapting it to their devices and also want to make sure the security of their devices is aligned with the latest security updates.

Metadata-agnostic Detection: Vanir fundamentally does not rely on metadata of the target system such as version number, commit histories and SBOMs. Vanir directly analyzes the actual source-code of the target system and pinpoints the files / functions requiring specific security patches. While Vanir user may choose to to filter out unwanted findings by providing metadata, its core detection logic is metadata-agnostic. This allows Vanir users the flexibility to utilize the tool with various options for different purpose.

Automated Signature Generation: The Vanir signature generation process is highly automated, enabling vulnerability publishers (such as CNAs and ecosystem security maintainers) to efficiently utilize Vanir and ensure security patch adoption by their downstream branch maintainers, streamlining workflows and optimizing resource allocation.

Runtime: Since Vanir uses source-code based static analysis to detect missing patches, the run time will be shorter compared to binary-based static analysis tools or dynamic analysis tools.

Transparency: Vanir operates as a standalone, fully open-source application. This empowers users to independently investigate and address any vulnerabilities identified by Vanir, without relying on or being hindered by responses from external service providers.

Continuously Updated Vulnerability Data: The Vanir tool is decoupled from the vulnerability data, and updated Android vulnerability data for Vanir will be maintained by the Google Android Security team in OSV. This will allow the Vanir users to simply run the Vanir with the latest vulnerability data without monthly updates. Further contributions from other CNAs (CVE Numbering Authorities) or system security maintainers would allow users to utilize Vanir for other ecosystems.

CI/CD Integration: Vanir is also provided in the form of Python library. Users can integrate the Vanir library into their own automated pipeline to verify any missing patches in a highly automated and systematic way.

---

Architectural Overview

Macro-architecture

Vanir mainly consists of two components — Signature Generator and Detector.

Signature Generator generates Vanir signatures for each vulnerability. The vulnerability can be from any source, but it should be defined in a OSV format, and should contain security patch information in the references field in the following format:

"references": [
  "type": "FIX",
  "url": public URL string to the fix commit
]

Vanir currently supports commits hosted in googlesource.com and git.codelinaro.org, but it can be easily extended to other hosts by adding new code extractor classes.

Once the generated signatures are shipped to OSV, the signatures can be transparently retrieved by Vanir Detector. Users may also use custom signatures by passing a JSON-format signature file to Vanir Detector. This can be useful for providing signatures of vulnerabilities that are not publicly announced yet or those for closed-source system.

The diagram below illustrates the macro-architecture of Vanir.

Micro-architecture

The following diagram depicts the internal architecture of Vanir Signature Generator and Vanir Detector.

Vanir was primarily designed to detect missing security patches with low false-positive rate in a sustainable and scalable way. To achieve the goal, Vanir utilizes multiple techniques in its internal components. This section offers a concise overview of several key Vanir components and spotlights specific techniques implemented within these components to support the overarching design objective.

Parser

The parser is a core component for extracting structural information from the target code. Since the original target of Vanir was Android, which consists of Linux kernel written in C and Android Framework written in C++ and Java, the current parser is implemented using Antlr4 C/C++ parser and Java parser. Vanir parser is designed to operate without build-time data. This approach enables Vanir to generate signatures and detect corresponding code blocks without requiring a build config.

Normalizer and Hasher

The extracted code blocks and structural information are passed to the normalizer and hasher components. The normalizer abstracts away security-insensitive tokens and the hahser convert the group of tokens into a 128-bit hash. The normalizer and hasher process each code block using two different signature generation techniques:

1. Line-based signature technique using code line n-grams, which is efficient for tolerating unrelated code mutations in distanced locations.

2. Function-based signature technique using abstracted function body, which is efficient for tolerating code mutations less likely to affect security.

While each signature type is specialized to tolerate certain types of code mutations, both approaches were designed conservatively so that they would not flag unrelated code as vulnerable code block. Vanir combines the two different approaches and make them complement each other and improve the overall sensitivity (i.e., lower the false-negative rate).

The line-based and function-based signature generation techniques are inspired by the code clone detection algorithms proposed by Jang et al. [1] and Kim et al. [2], respectively. While there are some differences in the technical details and implementations, each technique remains closely aligned algorithmically with its corresponding research work. Reading these papers would be beneficial for those seeking a deeper understanding of the theoretical underpinnings.

• [1] ReDeBug: Finding Unpatched Code Clones in Entire OS Distributions
• [2] VUDDY: A Scalable Approach for Vulnerable Code Clone Discovery

Refiner

The newly generated signatures are then passed to Refiner, which is another key component of Vanir to ensure low false-positive rate in a scalable and efficient way. The refiner tests newly generated signatures against the ground truth files which are already known as patched. The set of ground truth files for a signature may vary depending on the quality of the vulnerability data. If provided vulnerability data contains patch information for a single branch (e.g., upstream), then it simply uses the revision with the patch commit as the ground truth. If vulnerability data contains patch information for multiple branches, the refiner tries to test each signature against all different branches and classifies them different depending on the result (bad, version-specific, global). Since the refiner automatically filters out problematic signatures, Vanir signature publish