Txlog Server Documentation

I've built the Txlog Server to be the heart of the entire platform. It's where the magic happens: handling authentication, keeping your transaction logs safe, and providing the REST API that both our agents and UIs depend on. Think of it as the conductor of an orchestra, making sure every service stays in sync, data remains intact, and your security policies are actually followed.

TL;DR

Ready to get moving? You'll need a database first.

-- Create the database
CREATE DATABASE txlog;

Once that's sorted, you can fire up the server with a single Docker command.

# Run the server
docker run -d --name txlog-server \
-e PGSQL_HOST=db.example.com \
-e PGSQL_USER=txlog \
-e PGSQL_PASSWORD=txlog \
-e PGSQL_DB=txlog \
-p 8080:8080 \
ghcr.io/txlog/server:main

1. Tutorials

If you're just starting out, I've put together some lessons to help you find your feet.

• Setup Development Environment: I'll walk you through setting up the server locally.
• First API Request: Learn how to make requests to the API.

2. How-to Guides

Got a specific problem to solve? These guides are designed to help you get things done.

Authentication & Security

• Configure OIDC Authentication: Need to connect with Google or Keycloak? I've got you covered.
• Configure LDAP Authentication: If you're using Active Directory or OpenLDAP, start here.
• Configure Anonymous LDAP: Sometimes you don't have a service account, and that's okay.
• Discover LDAP Filters: Finding the right query filter can be a pain, but it doesn't have to be.
• Secure Deployment: Best practices for hardening your production environment.
• Manage API Keys: Here is how you create and revoke keys for your agents.

Operations

• Configure Data Retention: Don't let your database grow forever. Let's set some cleanup policies.
• Configure Topology Templates: Automate asset identification using hostname patterns.
• Manage OSV Vulnerabilities: Keeping threat data fresh is crucial, isn't it?
• Manage Inactive Servers: Cleaning up the dashboard by removing servers that no longer report.
• Search and Filter Assets: How to use the dashboard search bar and status filters.
• Run Database Migrations: Changing your schema shouldn't be scary.
• Deploy to Kubernetes: When you're ready for the big leagues, use this manifest.

Reports

• Detect Transaction Anomalies: Spotting unusual patterns before they become problems is key.

Development

• Run Tests: Let's make sure everything actually works before we ship it.

3. Reference

Looking for the nitty-gritty details? You'll find all the technical specs right here.

System

• API Reference: A high-level look at what the API can do.
• Database Schema: Every table, column, and relationship mapped out.
• Environment Variables: The full list of everything you can configure.
• Search Keywords Reference: All the magic keywords you can use in the asset search bar.

LDAP Specifics

• LDAP Cheatsheet: A quick reference for when you just need a variable name.
• LDAP Error Codes: Troubleshooting codes like 32, 49, or 50? I've been there.
• LDAP Filters Reference: Common patterns for the most popular directory services.

4. Explanation

Curious about why things work the way they do? I've written these to give you some background.

Architecture

• System Architecture: The "why" behind the design, the tech stack, and our distributed scheduler.
• Topology Matching Engine: How we dynamically identify environments and services.
• OSV Integration Details: How do we actually fetch and score vulnerabilities? It's all in here.
• Data Model: A closer look at the entities and how they relate to each other.
• How Search Works: Understanding the internal logic behind asset search and filtering.

Deep Dives

• LDAP Authentication Deep Dive: A thorough look at how we handle LDAP under the hood.
• LDAP Implementation Details: The actual structure of the code itself.
• LDAP Service Accounts FAQ: Best practices for managing those bind accounts.

5. API Documentation

Once your server is up and running, you can explore the API interactively at: http://localhost:8080/swagger/index.html

I've generated this from the code comments in docs/docs.go. If you make changes, just run make doc to keep everything up to date.