Import modes¶

Managing scan results as separate files leads to a fragmented and unclear view of your network. This problem becomes especially acute on large, dynamic scopes, where scans are often partial, repeated, or performed using varied scanning techniques.

Falcoria maintains a shared network state that represents all known hosts, ports, and services. Instead of treating scans as standalone events, scan results are applied to this shared state and accumulated into a single, consistent view. This approach is referred to as Data Aggregation. The shared state is stored and maintained by ScanLedger.

Import modes define how incoming scan reports update this shared state. They control how new data is applied to existing IPs and ports.

Falcoria provides four import modes: INSERT, APPEND, UPDATE, and REPLACE. Each mode represents a distinct strategy for applying new scan data.

IP-level behavior (applies to all modes)¶

Import modes never remove IPs.
If an IP exists in the incoming report and is missing in ScanLedger, it is always added.
This behavior is identical for INSERT, APPEND, UPDATE, REPLACE.

Port-level import semantics¶

This table shows how existing data and an incoming scan report are combined for a single port, depending on the selected import mode. Only port-level logic is shown. IP logic is handled separately.

ScanLedger (before)	Incoming report	APPEND Result	UPDATE Result	REPLACE Result
22/tcp open OpenSSH	22/tcp open	⚪ `22/tcp open OpenSSH`	⚪ `22/tcp open OpenSSH`	🟡 `22/tcp open`
22/tcp open	22/tcp open OpenSSH	⚪ `22/tcp open`	🟡 `22/tcp open OpenSSH`	🟡 `22/tcp open OpenSSH`
22/tcp open	22/tcp closed	⚪ `22/tcp open`	⚪ `22/tcp open`	🔴 `22/tcp closed`
—	22/tcp open OpenSSH	🟢 `22/tcp open OpenSSH`	🟢 `22/tcp open OpenSSH`	🟢 `22/tcp open OpenSSH`
22/tcp open	—	⚪ `22/tcp open`	⚪ `22/tcp open`	⚪ `22/tcp open`

Legend¶

🟢 new port was added
🟡 changed existing port was updated
⚪ unchanged existing port was not modified
🔴 removed port state changed to closed
— port does not exist in ScanLedger or incoming report

How to read this (short, but critical)¶

INSERT¶

operates on IPs only
ports are ignored
no port-level changes are applied

APPEND¶

adds port only if it does not exist
never updates existing ports
never closes a port

UPDATE¶

updates existing port if present in report
adds new ports if missing
ignores closed state on import
never closes a port

REPLACE¶

updates existing port if present in report
adds new ports if missing
applies closed state from the report
never removes ports that are absent from the report

When to use each import mode¶

INSERT¶

Use when you need to merge multiple scans with overlapping hosts
and only want to add IPs, without touching port data.

Typical scenarios:

merging recon scans that partially overlap by hosts
importing repeated scans of the same scope
aggregating host lists from different sources

APPEND¶

Use when scan results may be incomplete
and you want to add new ports without changing existing ones.

Typical scenarios:

fast or high-rate port scans
distributed scans with possible packet loss
scans where some open ports may be missed

UPDATE¶

Use when you want to update services and open ports, but do not want closed ports to affect existing data.

Typical scenarios:

service detection and version scanning
follow-up scans after initial port discovery
gradually improving service accuracy

REPLACE¶

Use when scan results are reliable and should be applied as-is to the current state.

Typical scenarios:

low-rate, high-confidence scans
internal network scans
scheduled scans used to refresh port state
safe for partial scans: ports missing from the report are not removed unless explicitly reported as closed