Asset-Vuln-Manager (AVM)

Getting Started

Your first operational path through AVM

The fastest way to understand AVM is to follow the normal operating path: load reference data, bring in assets and software, review canonical and unresolved mappings, generate alerts, and inspect the results.

How to think about AVM

AVM works best when approached as a workflow rather than as a single import screen or a single alert list. Reference-side data and inventory-side data both matter. Canonical linking improves inventory quality. Vulnerability data and product references provide the matching side. Alert generation then turns those inputs into operational results.

This means the first goal is not to make everything perfect in one step. The first goal is to understand the path from observed software to reviewable alert state.

Practical mindset: start with reference coverage and visibility, then improve linking quality, then review results.

What you need

Before starting AVM, prepare the following:

  • Java 21 or later
  • The AVM jar file
  • Either MySQL (recommended) or the embedded H2 database

Recommended path: use MySQL for normal operation and persistent data. Use H2 only for quick evaluation or local testing.

Get AVM

AVM is an open source project. You can explore the source code and download runnable artifacts from GitHub.

GitHub repository:
https://github.com/notegridx/asset-vuln-manager

Pre-built .jar files are published on GitHub Releases. This is the quickest way to try AVM without building from source.

Choose a runtime mode

AVM supports two common ways to get started.

Run with MySQL

Recommended for normal use, persistent data, and a more realistic operating environment.

Run with H2

Useful for quick evaluation, demos, and trying AVM without preparing a database server.

Configuration model

AVM can be configured using environment variables. These settings control database connection, security behavior, and runtime options.

You can provide configuration either:

  • via environment variables (recommended)
  • via command-line arguments (quick start)

Using environment variables (recommended)

export SPRING_DATASOURCE_URL=jdbc:mysql://localhost:3306/your-db-name
export SPRING_DATASOURCE_USERNAME=your-db-user
export SPRING_DATASOURCE_PASSWORD=your-db-password
export APP_SECURITY_BOOTSTRAP_ADMIN_ENABLED=true
export APP_SECURITY_BOOTSTRAP_ADMIN_PASSWORD=your-admin-password
export SERVER_PORT=8080

Then start AVM:

java -jar asset-vuln-manager-0.1.0.jar

Key idea: separating configuration from execution makes AVM easier to operate, automate, and deploy in environments such as systemd, Docker, or Kubernetes.

Run with MySQL (recommended)

For normal use, AVM is intended to run with MySQL. This is the recommended setup when you want persistent data and a more realistic operating environment.

Quick start (copy & paste, command-line arguments):

java -jar asset-vuln-manager-0.1.0.jar --spring.datasource.url="jdbc:mysql://localhost:3306/your-db-name" --spring.datasource.username="your-db-user" --spring.datasource.password="your-db-password" --app.security.bootstrap-admin.enabled=true --app.security.bootstrap-admin.password="your-admin-password" --server.port=8080

For readability (Linux/macOS): 

java -jar asset-vuln-manager-0.1.0.jar \
  --spring.datasource.url="jdbc:mysql://localhost:3306/your-db-name" \
  --spring.datasource.username="your-db-user" \
  --spring.datasource.password="your-db-password" \
  --app.security.bootstrap-admin.enabled=true \
  --app.security.bootstrap-admin.password="your-admin-password" \
  --server.port=8080

Notes:
MySQL must be available before startup.
A bootstrap admin is created only when explicitly enabled.
Adjust database name, credentials, admin password, and port for your environment.
Environment variables can be used instead of command-line arguments for more structured configuration.

Run with H2 (quick evaluation)

If you want to try AVM without preparing MySQL, you can also run it with the embedded H2 database. This is useful for quick local evaluation and feature exploration.

H2 lowers the setup barrier, but MySQL remains the better choice for ongoing use.

Quick start (H2):

java -jar asset-vuln-manager-0.1.0.jar --spring.profiles.active=h2 --app.security.bootstrap-admin.enabled=true --app.security.bootstrap-admin.password="your-admin-password" --server.port=8080

For readability (Linux/macOS): 

java -jar asset-vuln-manager-0.1.0.jar \
  --spring.profiles.active=h2 \
  --app.security.bootstrap-admin.enabled=true \
  --app.security.bootstrap-admin.password="your-admin-password" \
  --server.port=8080

Notes:
H2 is suitable for evaluation, demos, and quick local testing.
For persistent and production-oriented operation, use MySQL.
Environment variables can also be used for configuration instead of inline arguments.

First steps

Load reference data
→
Import assets and software
→
Review canonical mapping
→
Review unresolved mappings
→
Generate alerts
→
Review results

This is not only a first-time setup path. It is also the normal operating loop of the system.

Step 1: load reference data

Start by loading the reference-side data used by AVM. In practice, this means syncing both the canonical CPE dictionary and the vulnerability-side data used for later evaluation.

This step comes first because AVM depends on reference data for both canonical linking and vulnerability matching. Without canonical vendor and product references, software cannot be linked correctly. Without vulnerability data, later alert generation cannot produce meaningful results.

Sync CPE dictionary

Load the canonical vendor and product references that AVM uses during software resolution and matching.

Sync vulnerability data

Load CVE-side data so later alert generation can evaluate installed software against stored conditions.

For the related operational surfaces, see Admin.

Step 2: import assets and software

Once reference data is available, bring in asset and software inventory. Assets provide the host anchor for the environment. Software rows provide the inventory-side evidence that later linking and evaluation will use.

In AVM, software import is most useful when asset identity is already present, because software rows are tied to assets and later alerts are meaningful only in host context.

Import assets first

Create the host records that software rows will attach to.

Then import software

Add observed software rows with as much vendor, product, publisher, and version data as you have.

For field-level details and JSON examples, see Import.

Step 3: review canonical mapping

After import, review how software is linked to canonical vendor and product identity. This is one of the most important steps in AVM because later vulnerability evaluation depends on the quality of this linkage.

AVM can suggest candidate mappings, but the review surface remains visible and controllable. Operators can inspect the suggested candidate set and decide whether the software should be linked, adjusted, or left unresolved for further review.

Candidate-driven review

AVM surfaces candidate vendor and product mappings so linking is reviewable rather than hidden.

User-controlled linkage

Operators can confirm, adjust, or decline mappings instead of treating automated resolution as unquestionable truth.

For the model behind this, see Concepts and Admin.

Step 4: review unresolved mappings

Some software rows will still remain unresolved. This is expected, especially when source data is noisy or naming differs from the canonical dictionary.

Review unresolved mappings early. They tell you where AVM still needs help understanding the identity of installed software and where aliases, synonyms, or later review actions may improve coverage.

Why do this early

Better canonical coverage improves downstream matching quality.

What to look for

Vendor naming variation, product naming ambiguity, and rows that need alias or synonym support.

For the review model behind this, see Concepts and Admin.

Step 5: generate alerts

Once reference data is loaded and inventory has enough canonical coverage, generate alert state. This is where AVM turns software, canonical identity, version evidence, and stored vulnerability conditions into operational results.

Generation is also important later, after canonical coverage improves. When aliases, synonyms, or review actions change the identity picture, alert state should be updated to reflect that improvement.

Software inventory
→
Canonical identity
→
Vulnerability conditions
→
Alert state

For the underlying decision path, see Matching.

Step 6: review the results

Once alerts exist, review them together with the context that produced them. AVM is designed so that operators can inspect not only the final result but also the quality of the path behind it.

Useful questions at this stage include:

Are important software rows still unresolved?

If so, matching coverage may still be incomplete.

Is version data present where it matters?

Weak version evidence can reduce applicability precision.

Do alert results line up with the software context?

Alerts should make sense when reviewed together with software identity and asset context.

What to expect on the first pass

A first cycle usually does not produce a perfectly clean result. Some software will already be linkable and matchable. Some will remain unresolved. Some will have strong version evidence, and some will not.

That is normal. AVM is designed for iterative improvement, not for pretending that one pass solves all naming and applicability questions.

Expected

A mix of resolved software, unresolved software, and reviewable alert results.

Not required

Perfect canonical coverage before you can learn something from the system.

First 30 minutes with AVM

If you want a practical first session, use this sequence:

1. Sync reference data

Load the CPE dictionary and vulnerability-side data before expecting linking or alert generation to work well.

2. Add a small asset set

Import a limited number of assets so the host context stays easy to inspect.

3. Add a realistic software sample

Include vendor, product, publisher, and version values where possible.

4. Review canonical and unresolved mappings

This quickly shows how AVM distinguishes raw inventory from canonical identity and where review is still needed.

5. Generate alerts

Review the resulting alert state and trace it back to the software and asset context.

Suggested reading order

Once you have seen the basic workflow, the most useful next reading order is:

  1. Concepts
  2. Data Model
  3. Matching
  4. Import
  5. Admin

This order helps move from the high-level operating model to the more detailed mechanics behind it.

Example

A new user first syncs canonical reference and vulnerability data, then imports a small set of assets and software. Some software rows are linked to canonical vendor and product references immediately, while others remain unresolved because the source naming is too broad or unusual. The user reviews canonical and unresolved mappings, improves reference coverage, and generates alerts.

After that first cycle, the user already understands the most important AVM idea: the system is not only ingesting inventory, it is helping turn observed software into reviewable and improvable vulnerability context.

What AVM is trying to avoid

One-click black box setup

AVM is designed to keep the operating path visible.

Confusing import with full resolution

Imported software may still need canonical review.

Treating alerts as the only useful output

Canonical review and unresolved mappings are also valuable.

Hiding iteration

Improving aliases, backfill coverage, and alert generation is part of normal use.

Summary

Getting started with AVM is best understood as learning one operational loop: load reference data, import assets and software, review canonical and unresolved mappings, generate alerts, and inspect the result in context.

Once that loop is clear, the rest of AVM becomes easier to understand. The system’s value comes not only from producing alerts, but from making the path to those alerts visible and improvable.