docs

README

Txlog Server Documentation

Welcome to the Txlog Server documentation. This documentation is divided into four types of guides:

📚 Documentation Index

1. Tutorials (Learning-oriented)

Start here if you are new to the project.

• Getting Started: Set up the server locally with Docker.
• Your First API Request: Learn how to interact with the API.

2. How-to Guides (Task-oriented)

Step-by-step guides to achieve specific goals.

Authentication & Security

• Configure OIDC Authentication: Connect with Google, Keycloak, etc.
• Configure LDAP Authentication: Connect with Active Directory or OpenLDAP.
• Configure Anonymous LDAP: For servers without service accounts.
• Discover LDAP Filters: How to find the right query filters for your directory.
• Manage API Keys: Create and revoke keys for agents.

Operations

• Configure Data Retention: Manage database cleanup policies.
• Manage OSV Vulnerabilities: Update, fetch, and rebuild OSV threat data.
• Search and Filter Assets: How to use the dashboard search and status filters.
• Run Database Migrations: Apply schema changes safely.
• Deploy to Kubernetes: Production deployment manifest.

Reports

• Detect Transaction Anomalies: Detect and manage unusual transactions.

Development

• Add a New Endpoint: Workflow for contributors.
• Run Tests: Execute the test suite.

3. Reference (Information-oriented)

Technical descriptions and specifications.

System

• API Reference: High-level API overview.
• Database Schema: Tables, columns, and relationships.
• Environment Variables: Complete configuration reference.

LDAP Specifics

• LDAP Cheatsheet: Quick reference for variables and common setups.
• LDAP Error Codes: Troubleshooting common error codes (32, 49, 50).
• LDAP Filters Reference: Common filter patterns for AD, OpenLDAP, etc.

4. Explanation (Understanding-oriented)

Background knowledge and design decisions.

Architecture

• System Architecture: High-level design, stack, and distributed scheduler.
• OSV Integration Details: How vulnerability fetching, payload batching, and scoring works.
• Data Model: Entities and relationships explanation.

Deep Dives

• LDAP Authentication Deep Dive: Comprehensive guide to how LDAP auth works.
• LDAP Implementation Details: Internal code structure of the LDAP module.
• LDAP Service Accounts FAQ: Best practices for bind accounts.
• Testing Strategy: Overview of the test suite and coverage goals.

---

�️ Tools & Scripts

The docs/ directory also contains useful scripts for administrators:

• ldap-discovery.sh: An interactive script to help you discover your LDAP server's structure and test filters.

🔌 API Documentation (Swagger)

When the server is running, interactive API documentation is available at: http://localhost:8080/swagger/index.html

• Source: docs/docs.go (Generated from code comments)
• Update: Run make doc to regenerate.

---

🤝 Contributing

When adding new features, please update the relevant documentation sections above. Ensure all Markdown files pass markdownlint.

Documentation

Index

• Variables

Variables

var SwaggerInfo = &swag.Spec{
	Version:          "v1",
	Host:             "",
	BasePath:         "",
	Schemes:          []string{},
	Title:            "Txlog Server",
	Description:      "The centralized system that stores transaction data",
	InfoInstanceName: "swagger",
	SwaggerTemplate:  docTemplate,
	LeftDelim:        "{{",
	RightDelim:       "}}",
}

SwaggerInfo holds exported Swagger Info so clients can modify it