Configuring Source Intelligence

The nv.config file lets you supply values and analysis settings that cannot be inferred from source alone. For example, an API prefix such as /api/v1 may come from an environment variable without a default value. Source Intelligence records that unresolved value in nv.config so you can generate a more accurate OpenAPI document on the next run.

Prerequisites

Make sure the NightVision CLI is installed: Installing the CLI.

Tutorial

In this tutorial, you’ll learn how to tweak the nv.config file that was generated by nightvision openapi extract to create the most accurate OpenAPI definition.

1. First, clone the example GitHub repository and enter the directory:

git clone https://github.com/nvsecurity/ReplacementsExample.git
cd ReplacementsExample

2. Run the following command to perform the extraction:

nightvision openapi extract ./ -o openapi-spec.yml -l dotnet --no-target

3. Open the generated openapi-spec.yml file. You’ll notice that there is an unresolved variable in the URL path - ApiPrefix. A trimmed version of the file is shown below for brevity:

paths:
  # Notice how the unresolved variable is included in the path.
  # It should be `/api/v2`, based on the appsettings.json file.
  /ApiPrefix:
    get:
      # The x-source value tells you where the endpoint was declared.
      # Start looking from here to investigate where the unresolved variable
      # originates from.
      # If you dig into this file, you'll notice that it uses a convention in
      # .NET that pulls the value from the appsettings.json file.
      x-source: Program.cs~~14

4. There is a new file in the directory: nv.config. Notice that the first value in the replacements object is set to null. That is the value that must be modified to properly resolve the variable.

{
  "replacements": {
    "Microsoft.AspNetCore.Builder.WebApplication.Services.GetRequiredService().Value.ApiPrefix": null
  }
}

5. Now that we know the variable name, let’s find the value. Open the appsettings.json file. Observe that the Prefix value is set to api/v2. That is the replacement value that you should set in the nv.config file.
6. Modify the nv.config file to include the api/v2 value instead of null:

{
 "replacements": {
    "Microsoft.AspNetCore.Builder.WebApplication.Services.GetRequiredService().Value.ApiPrefix": "api/v2"
  }
}

7. Now generate a new OpenAPI file by running the NightVision Swagger extraction again:

nightvision openapi extract ./ -o openapi-spec.yml -l dotnet --no-target

8. Observe that the openapi-spec.yml file includes the proper variables:

paths:
  # The proper value is now included in the OpenAPI file.
  /api/v2:
    get:
      x-source: Program.cs~~14

Configuration location and safety

By default, Source Intelligence resolves nv.config separately for each language group, using the file in that group’s first detected scan directory. Use --config to select one file explicitly, especially when extracting several applications from a monorepo:

nightvision openapi extract services/api \
  --config config/source-intelligence.json \
  --no-target

If the selected file does not exist, Source Intelligence can create it as it finds replacement keys. It never overwrites an existing file that contains malformed JSON or a setting with the wrong type. Instead, it logs the error and continues with an empty configuration; fix the file and run the extraction again for its settings to take effect.

Default security

Use defaultSecurity when authentication is enforced outside the scanned source, such as in a private package, API gateway, or service mesh. It supplies a security requirement only to matching operations that do not already have a resolved requirement:

{
  "replacements": {},
  "defaultSecurity": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT",
    "description": "Gateway-issued access token",
    "pathPrefixes": ["/api", "/v2"],
    "excludePathPrefixes": ["/api/token", "/api/health"]
  }
}

Supported schemes are HTTP bearer and basic, plus OpenAPI apiKey credentials in a header, query, or cookie. For an API key, set type to apiKey and provide name and in. The optional key becomes the name under components.securitySchemes; it defaults to DefaultAuth.

Prefixes match complete path segments, so /api includes /api/items but not /apiary. Exclusions are evaluated first. An empty pathPrefixes list applies to every path.

The setting is a floor, not an override: requirements discovered from source remain unchanged. Because the generated OpenAPI document cannot distinguish a deliberately anonymous route from a route whose guard was not found, add login, token, health, and other public endpoints to excludePathPrefixes.

Analysis settings

These optional settings help with large or unusual applications:

Setting	Behavior
foreachLimit	Limits results accumulated while interpreting a loop. The default is 90; 0 removes the limit. A smaller value can reduce memory use but may omit routes.
memoize	Reuses interpreted function results. It is off by default and can help applications where repeated interpretation times out or loses routes.
stallWarningInterval	Controls Python no-progress warnings using a duration such as "90s" or "5m". The default is 60 seconds; "0" disables the watchdog. The warning reports a stall but does not stop extraction.

In NightVision CLI 0.17.0, foreachLimit, memoize, and stallWarningInterval are configured only in nv.config.

For Micronaut applications, securityReporting can be sast (the default) or dast. sast reports security exactly as the analyzed configuration enables it. Set dast only when the deployed application enables security even though the configuration being scanned explicitly disables it.