packages

The packages command provides utilities for managing the package vulnerability database and performing specialized analysis comparing packages directly against app bundles. It operates on the clean database (separate from the main hedis database).

Usage

hedis packages [flags]

Flags

Database Management

-u, --update-database

boolean

default:"false"

Update the database with packages from direct-vulnerabilities.json. Creates package entries with vulnerability metadata.

--create-hashes

boolean

default:"false"

Generate function fingerprints for all packages in the database across all React Native versions. This is a comprehensive operation that:

Fetches RN baselines
Processes each package across all RN environments
Generates and stores hashes
Filters out framework functions using baselines

Analysis Modes

-s, --specific-analysis

boolean

default:"false"

Enable specific package-to-app analysis mode. Compare a specific package HBC file against an app bundle with baseline filtering.

-d, --analyze-with-database

boolean

default:"false"

Analyze an app bundle against all packages in the database. Generates a ranked list of package matches.

Analysis Parameters

-p, --specific-package

string

Path to the package HBC file. Required when --specific-analysis is enabled.

-a, --compare-to-app-bundle

string

Path to the app bundle HBC file to analyze. Required for both analysis modes.

-o, --output-file

string

Path to the output file for analysis results. Defaults to <bundle-name>_match_results.txt for database analysis.

-v, --verbose

boolean

default:"false"

Enable verbose output for detailed logging.

Examples

Update Package Database

Import packages from vulnerability JSON:

hedis packages --update-database

What it does:

Reads direct-vulnerabilities.json from the current directory
Extracts unique packages with version ranges
Creates PackageWithVulnerabilitiesModel entries in the clean database
Associates packages with their GHSA IDs and severity levels

Example output:

Connecting to database...
Database connected
Found 342 packages in direct-vulnerabilities.json
Total of 1247 package versions
Updating packages in database...

Generate Hashes for All Packages

Create fingerprints for database packages:

hedis packages --create-hashes --verbose

This is an extremely time-consuming operation that processes each package across all 11 React Native versions. It can take several days to complete for hundreds of packages.

Workflow:

Fetch RN baselines from database
For each package:
- For each RN version:
  - Install package
  - Metro bundle
  - Hermes compile
  - Disassemble and hash
  - Filter baseline matches
  - Store in database

Specific Package Analysis

Compare a package against an app bundle with baseline filtering:

hedis packages \
  --specific-analysis \
  --specific-package [email protected] \
  --compare-to-app-bundle production-app.bundle \
  --output-file analysis.txt

What it does:

Extracts Hermes bytecode version from both bundles
Generates function object hashes
Identifies the best-matching RN baseline based on bytecode version
Filters out framework functions from the app bundle
Compares package hashes against filtered app hashes
Reports match percentages across three hash types

Example output:

App bundle HBC version: 94
Found 3841 function objects in app bundle
Package HBC version: 94
Found 156 function objects in package

Generating hashes for app bundle...
Generated 3841 hashes for app bundle
Found 3841 unique hashes in app bundle

Generating hashes for package...
Generated 156 hashes for package

Matching hashes with RN baselines...
Found 2584 hashes for app bundle that matched the best RN baseline: 0.71

Comparing 1257 app bundle hashes with 156 package hashes...
Structural: 142/156 package hashes matched (91.03%)
ContentIR1: 98/124 package hashes matched (79.03%)
ContentIR2: 131/145 package hashes matched (90.34%)
Combined: 147/156 package hashes matched
Total: 371/1257 package hashes matched (29.51%)

Database Analysis

Analyze an app bundle against all packages in the database:

hedis packages \
  --analyze-with-database \
  --compare-to-app-bundle production-app.bundle \
  --output-file matches.txt

What it does:

Disassembles the app bundle and generates hashes
Identifies best RN baseline match
Filters framework functions from app hashes
Queries database for all package hashes matching the RN version
Compares app against each package
Ranks results by combined match count
Writes full results to output file

Example output:

Getting RN baselines...
Extracting HBC versions...
App bundle HBC version: 94
Found 3841 function objects in app bundle

Matching hashes with RN baselines...
Found 1257 hashes for app bundle that matched the best RN baseline: 0.71

Getting hashes from database...
Found 342 packages with a total of 45612 hashes in database for RN version 0.71

Comparing app bundle hashes with database hashes...

Top 10 matches:
1. [email protected] (ObjectId(...))
Combined: 147/156 (94.23%) package hashes matched

2. [email protected] (ObjectId(...))
Combined: 89/95 (93.68%) package hashes matched

3. @react-native-async-storage/[email protected] (ObjectId(...))
Combined: 67/78 (85.90%) package hashes matched
...

Output file format:

147/156 (94.23%) [email protected]
89/95 (93.68%) [email protected]
67/78 (85.90%) @react-native-async-storage/[email protected]
...

Package versions with the highest combined matches:
react-native-device-info: [email protected] (147/156 (94.23%))
react-native-fs: [email protected] (89/95 (93.68%))
...

Combined Workflow

Build database and analyze:

hedis packages --update-database

Analysis Metrics

The analysis compares three hash types:

Structural Hash

Based on instruction opcode bigrams (sequences)
Resistant to identifier renaming and string changes
Best for detecting code structure similarity

Content IR1 Hash

Based on non-identifier strings (literals, messages, etc.)
Good for detecting string constant similarity
Vulnerable to string obfuscation

Content IR2 Hash

Based on identifiers and object references
Good for detecting variable/function name similarity
Vulnerable to minification and obfuscation

Combined Metric

A function matches if any of the three hashes match. The combined metric gives the best overall indication of package presence.

Baseline Filtering

Both analysis modes use RN baseline filtering:

Extract HBC version from the app bundle
Find best baseline match by comparing app hashes against all RN baselines
Filter framework hashes that match the baseline
Compare remaining hashes against package fingerprints

This removes React Native framework functions to reduce false positives.

Database Schema

The clean database uses these collections:

{
  "package_name": "react-native-device-info",
  "package_version": "8.1.0",
  "ghsa_ids": ["GHSA-xxxx-xxxx-xxxx"],
  "severity": "HIGH",
  "vulnerable": true,
  "created_at": "2024-01-15T10:30:00Z"
}

hashes

{
  "package_id": "ObjectId(...)",
  "react_native_version": "0.71",
  "hash": {
    "structural_hash": "a3f2c1d9e8b7...",
    "structural_raw": "LoadConstUndefined|Ret|CreateEnvironment|...",
    "content_ir1_hash": "9e8b7c6d5a4f...",
    "content_ir1_raw": "navigate|title|home",
    "content_ir2_hash": "c1d9e8b7a3f2...",
    "content_ir2_raw": "navigationState|screenProps",
    "relative_function_index": 42
  }
}

Environment Variables

MONGO_CONNECTION_STRING

string

required

MongoDB connection URI.

OS_HERMES

string

required

Platform-specific Hermes binary: osx-bin or linux64-bin.

File Requirements

direct-vulnerabilities.json

Required for --update-database:

[
  {
    "packageName": "react-native-device-info",
    "vulnerableVersions": ["8.0.0", "8.1.0"],
    "ghsaIds": ["GHSA-xxxx-xxxx-xxxx"],
    "severity": "HIGH"
  }
]

Performance Considerations

Hash Generation

Processing all packages can take days for large package sets
Each package is installed and compiled 11 times (once per RN version)
Uses parallel RN version processing (max 4 concurrent)

Database Analysis

Queries all package hashes for the detected RN version
Performs in-memory comparisons
Sorts results by combined match count
Typically completes in seconds to minutes depending on database size

Common Use Cases

Vulnerability Research

Build a database of vulnerable package fingerprints:

hedis packages --update-database
hedis packages --create-hashes

App Auditing

Scan a production app for known vulnerable packages:

hedis packages \
  --analyze-with-database \
  --compare-to-app-bundle app.bundle \
  --output-file audit-report.txt

Package Verification

Verify if a specific package version is in an app:

hedis packages \
  -s \
  -p [email protected] \
  -a app.bundle \
  -o verification.txt

Notes

This command uses a separate clean database (not the main hedis database)
Baseline filtering significantly improves accuracy by removing framework noise
Match percentages >80% indicate strong confidence the package is present
The database analysis output includes both per-version and per-package rankings
Results are sorted by combined matches (any hash type matching)

Get Started

Core Concepts

CLI Commands

Guides

Architecture

packages

Usage

Flags

Database Management

Analysis Modes

Analysis Parameters

Examples

Update Package Database

Generate Hashes for All Packages

Specific Package Analysis

Database Analysis

Combined Workflow

Analysis Metrics

Structural Hash

Content IR1 Hash

Content IR2 Hash

Combined Metric

Baseline Filtering

Database Schema

packages

hashes

Environment Variables

File Requirements

direct-vulnerabilities.json

Performance Considerations

Hash Generation

Database Analysis

Common Use Cases

Vulnerability Research

App Auditing

Package Verification

Notes

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Commands

Guides

Architecture

​Usage

​Flags

​Database Management

​Analysis Modes

​Analysis Parameters

​Examples

​Update Package Database

​Generate Hashes for All Packages

​Specific Package Analysis

​Database Analysis

​Combined Workflow

​Analysis Metrics

​Structural Hash

​Content IR1 Hash

​Content IR2 Hash

​Combined Metric

​Baseline Filtering

​Database Schema

​packages

​hashes

​Environment Variables

​File Requirements

​direct-vulnerabilities.json

​Performance Considerations

​Hash Generation

​Database Analysis

​Common Use Cases

​Vulnerability Research

​App Auditing

​Package Verification

​Notes

Build docs developers (and LLMs) love

Usage

Flags

Database Management

Analysis Modes

Analysis Parameters

Examples

Update Package Database

Generate Hashes for All Packages

Specific Package Analysis

Database Analysis

Combined Workflow

Analysis Metrics

Structural Hash

Content IR1 Hash

Content IR2 Hash

Combined Metric

Baseline Filtering

Database Schema

packages

hashes

Environment Variables

File Requirements

direct-vulnerabilities.json

Performance Considerations

Hash Generation

Database Analysis

Common Use Cases

Vulnerability Research

App Auditing

Package Verification

Notes