Skip to content

scanledger

ScanLedger is the component responsible for aggregating scan data into a single shared, living report.

If you want to quickly try the workflow described in the article, use the Docker Compose quick start below. It is the recommended way to run ScanLedger locally.

This guide walks you through the practical scenarios described in the article, showing how ScanLedger solves the problem of fragmented scan data in team-based engagements.

The fastest way to get ScanLedger up and running is using the automated quickstart script. Follow these steps:

1. Clone the Repository

git clone https://github.com/Falcoria/scanledger.git
cd scanledger

2. Run the Quickstart Script

./quickstart.sh

The quickstart script will automatically:

  • Generate TLS certificates for HTTPS communication
  • Create environment configuration by copying .env.example to .env
  • Generate secure credentials:
  • Random PostgreSQL password (16 alphanumeric characters)
  • Random admin token (16 alphanumeric characters)
  • Random tasker token (16 alphanumeric characters)
  • Configure Docker networking (sets PostgreSQL host to "postgres")
  • Start all services with Docker Compose
  • Perform health checks to verify the installation
  • Display the admin token for immediate use

3. Save Your Admin Token

When the script completes, it will display your generated admin token:

========================================
Admin Token: abc123def456ghi7
========================================

Important: Copy and save this token securely! You'll need it to authenticate with the ScanLedger API and use the console client tools.

4. Using with Console Client

Once ScanLedger is running, you can use the admin token with the Falcoria CLI tool:

Falcoria CLI (falcli)

Follow the installation instructions from the repository above.

After installation, modify the configuration file:

./app/data/profiles/default.yaml

Set the following values:

backend_base_url: https://localhost # the root URL of your ScanLedger instance
tasker_base_url: <tasker_url>   # not used in this guide
token: <ADMIN TOKEN FROM THE STEP ABOVE>

Example Workflow

With your admin token configured, you can now manage projects and data in ScanLedger:

# Create a new project
./falcli.py project create pentest_project

# List all projects
./falcli.py project list

# Import initial scan data - two separate reports
./falcli.py project ips import -f scan_report_samples/A_B_http_only.xml --mode insert
./falcli.py project ips import -f scan_report_samples/B_C_http_only.xml --mode insert

# View imported data (ScanLedger has already de-duplicated IPs from both reports)
./falcli.py project ips get

# Add more comprehensive port data to existing hosts (no history tracking)
./falcli.py project ips import -f scan_report_samples/full_tcp.xml --mode append --no-history

# Replace with fresh scan results (tracks changes over time)
./falcli.py project ips import -f scan_report_samples/rescan.xml --mode replace

# View historical changes tracked by replace mode
./falcli.py project ips history

# Export all project data in Nmap XML format
./falcli.py project ips download

Import Modes and Examples

ScanLedger supports flexible import modes for different scenarios. For detailed import modes behavior, see Import Modes Documentation.

Note on Scanning: ScanLedger specializes in storing and managing scan results. To initiate new scans (commands like scan start and scan status), you would use the separate Falcoria Tasker component. This architectural separation keeps the system clean and scalable.

Additional Resources: For advanced configuration and alternative installation options, see the ScanLedger GitHub repository.