### Example Complete State File

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/types.md

An example of a fully populated state.json file, showing typical values for database configurations including URLs, retry information, and versioning.

```json
{
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "dbs": {
        "main.cvd": {
            "url": "https://database.clamav.net/main.cvd",
            "retry after": 0,
            "last modified": 1719000000,
            "last checked": 1719100000,
            "DNS field": 1,
            "local version": 60,
            "CDIFFs": ["main-59-60.cdiff"]
        },
        "daily.cvd": {
            "url": "https://database.clamav.net/daily.cvd",
            "retry after": 0,
            "last modified": 1719050000,
            "last checked": 1719100000,
            "DNS field": 2,
            "local version": 2847,
            "CDIFFs": []
        },
        "bytecode.cvd": {
            "url": "https://database.clamav.net/bytecode.cvd",
            "retry after": 0,
            "last modified": 1718950000,
            "last checked": 1719100000,
            "DNS field": 7,
            "local version": 331,
            "CDIFFs": []
        }
    }
}
```

--------------------------------

### Example Config File

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/types.md

An example config.json file demonstrating how to configure cvdupdate's operational parameters, including custom log and database directories, and network settings.

```json
{
    "nameservers": "8.8.8.8,8.8.4.4",
    "max_retries": 3,
    "logs_enabled": true,
    "logs_directory": "/var/log/cvdupdate",
    "logs_rotate": true,
    "logs_to_keep": 30,
    "dbs_directory": "/var/www/html/clamav",
    "cdiffs_rotate": true,
    "cdiffs_to_keep": 30,
    "state_file": "/var/lib/cvdupdate/state.json"
}
```

--------------------------------

### Example Help Output with Aliases

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/AliasedGroup.md

Illustrates how the `AliasedGroup` formats the help output to include command aliases inline.

```text
Commands:
  list (ls)      List the DB names found in the database directory.
  status (s)     Show status of one or all databases.
  update (u)     Update the DBs from the internet.
  add            Add a db to the list of known DBs.
  remove (rm)    Remove a db from the list of known DBs.
  config (cf)    Commands to configure.
  clean (cl)     Commands to clean up.
  serve          Serve up the database directory.
```

--------------------------------

### config.json Example

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/CVDUpdate.md

Shows a sample configuration file in JSON format, detailing settings for network nameservers, retry attempts, log management, and database paths.

```json
{
    "nameservers": "8.8.8.8,8.8.4.4",
    "max_retries": 3,
    "logs_enabled": true,
    "logs_directory": "~/.cvdupdate/logs",
    "logs_rotate": true,
    "logs_to_keep": 30,
    "dbs_directory": "~/.cvdupdate/database",
    "cdiffs_rotate": true,
    "cdiffs_to_keep": 30,
    "state_file": "~/.cvdupdate/state.json"
}
```

--------------------------------

### state.json Example

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/CVDUpdate.md

Provides an example of the state.json file, which stores the unique identifier for analytics and a list of managed databases with their respective states.

```json
{
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "dbs": {
        "main.cvd": {...},
        "daily.cvd": {...},
        "bytecode.cvd": {...}
    }
}
```

--------------------------------

### State File Structure Example

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/INDEX.md

Illustrates the JSON structure of the state file, detailing database information, versioning, and update status.

```json
{
    "uuid": "unique-installation-id",
    "dbs": {
        "database-name": {
            "url": "https://...",
            "retry after": 0,
            "last modified": 1234567890,
            "last checked": 1234567890,
            "DNS field": 1,
            "local version": 60,
            "CDIFFs": ["main-59-60.cdiff"]
        }
    }
}
```

--------------------------------

### Start Test Server via CLI

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/README.md

Initiate a local test server for serving ClamAV signature databases on a specified port.

```bash
cvd serve 8000
```

--------------------------------

### Database State Structure Example

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/CVDUpdate.md

Illustrates the expected structure for each database entry within the 'state' dictionary, including download URLs, timestamps, and version information.

```python
{
    "url": str,           # HTTP/HTTPS URL for download
    "retry after": int,   # Unix timestamp for rate-limit cooldown (0 = ready)
    "last modified": int, # Unix timestamp of last successful download
    "last checked": int,  # Unix timestamp of last version check
    "DNS field": int,     # Index in DNS TXT record (0 for non-CVD)
    "local version": int, # Local version number (0 if not downloaded)
    "CDIFFs": list        # List of available CDIFF patch files
}
```

--------------------------------

### Install cvdupdate from PyPI

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Use this command to install the cvdupdate package from the Python Package Index.

```bash
python3 -m pip install --user cvdupdate
```

--------------------------------

### Docker with Extra Databases

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/configuration.md

This example demonstrates how to add extra databases to cvdupdate on startup by providing a comma-separated list of database names and URLs via the EXTRA_DATABASES environment variable.

```bash
# Add extra databases on startup
docker run -d \
  -v "$(pwd)/database:/cvdupdate/database" \
  -e EXTRA_DATABASES="custom.ndb:https://example.com/custom.ndb,other.yara:https://example.com/other.yara" \
  cvdupdate:latest
```

--------------------------------

### Start Docker Compose Services

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Starts the services defined in the docker-compose.yaml file in detached mode. This command will also create the necessary volumes if they do not already exist.

```bash
docker compose up -d
```

--------------------------------

### Initialize CVD Configuration

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/OVERVIEW.md

Sets the directory where virus definition databases will be stored. This is a one-time setup command.

```bash
# Initial setup
cvd config set --dbs-directory /var/www/clamav
```

--------------------------------

### Directory Listing Example for MirrorRequestHandler

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/MirrorRequestHandler.md

Demonstrates the output of a directory listing request made to MirrorRequestHandler. It shows that dotfiles and dotdirectories are hidden from the listing.

```text
Index of /
[ICO]       Name                    Last modified      Size  Description
[PARENTDIR] Parent Directory        -                 -
[TXT]       main.cvd               2024-06-22        50M
[TXT]       daily.cvd              2024-06-22        100M
[TXT]       bytecode.cvd           2024-06-22        10M
[TXT]       dns.txt                2024-06-22        1K
```

--------------------------------

### Set up and Schedule Private Database Mirror

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/OVERVIEW.md

Use these commands for a one-time setup of a private ClamAV database mirror and to schedule regular updates using cron.

```bash
# One-time setup
cvd config set --dbs-directory /var/www/clamav
cvd update

# Schedule regular updates
crontab -e
# Add: 30 */4 * * * /usr/local/bin/cvd update
```

--------------------------------

### Example Database Configuration Record: Standard ClamAV Main Database

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/types.md

Illustrates a typical database configuration record for the standard ClamAV main database. This example shows expected values for URL, timestamps, DNS field, local version, and CDIFFs.

```json
{
    "url": "https://database.clamav.net/main.cvd",
    "retry after": 0,
    "last modified": 1719000000,
    "last checked": 1719100000,
    "DNS field": 1,
    "local version": 60,
    "CDIFFs": ["main-59-60.cdiff", "main-58-59.cdiff"]
}
```

--------------------------------

### Example Database Configuration Record: Rate-Limited Database on Cooldown

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/types.md

Shows an example of a database configuration record for a database that is currently on cooldown due to rate limiting. The 'retry after' field indicates the Unix timestamp when the server will permit retries.

```json
{
    "url": "https://database.clamav.net/daily.cvd",
    "retry after": 1719150000,
    "last modified": 1719000000,
    "last checked": 1719100000,
    "DNS field": 2,
    "local version": 2847,
    "CDIFFs": []
}
```

--------------------------------

### Allowed Paths Example for MirrorRequestHandler

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/MirrorRequestHandler.md

Shows paths that MirrorRequestHandler will allow, serving the requested file or directory. These are standard file and subdirectory requests.

```text
GET /main.cvd         → 200 OK (file served)
GET /daily.cvd        → 200 OK
GET /subdirectory/db  → 200 OK (if exists)
```

--------------------------------

### Example Database Configuration Record: Custom Non-CVD Database

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/types.md

Provides an example of a database configuration record for a custom, non-CVD database. This record demonstrates the structure when the database is not a ClamAV CVD file, with DNS field and local version set to 0.

```json
{
    "url": "https://example.com/custom.ndb",
    "retry after": 0,
    "last modified": 1719050000,
    "last checked": 1719100000,
    "DNS field": 0,
    "local version": 0,
    "CDIFFs": []
}
```

--------------------------------

### start Function

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/OVERVIEW.md

Starts the background update thread with a specified interval. This function is used to schedule periodic database updates.

```APIDOC
## Function start(interval)

### Purpose
Start background update thread.

### Parameters
#### Path Parameters
- **interval** (any) - Required - The interval at which to start the background update thread.

### Module
cvdupdate.auto_updater
```

--------------------------------

### Configure and Start MirrorRequestHandler Server

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/MirrorRequestHandler.md

Configures the protocol version and initializes an HTTPServer with MirrorRequestHandler. This is typically used when starting a local mirror server for CVD updates.

```python
MirrorRequestHandler.protocol_version = 'HTTP/1.0'
httpd = HTTPServer(('', 8000), MirrorRequestHandler)
```

--------------------------------

### CvdUpdate Usage Example

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/CvdStatus.md

Demonstrates how to instantiate CVDUpdate and call db_update. Internal methods use CvdStatus for status tracking.

```python
from cvdupdate.cvdupdate import CVDUpdate, CvdStatus

updater = CVDUpdate()

# db_update() returns error count, not CvdStatus directly
# But internal methods use CvdStatus for status tracking
error_count = updater.db_update()
# Returns: int (number of databases that errored)
```

--------------------------------

### Log File Format Example

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/types.md

Illustrates the standard log entry format including timestamp, log level, and message. Used for tracking update processes.

```text
2024-06-22 14:30:45 - INFO:  Checking main.cvd for update from https://database.clamav.net/main.cvd
2024-06-22 14:30:46 - DEBUG: Checking main.cvd version via DNS TXT entry query of current.cvd.clamav.net
2024-06-22 14:30:47 - INFO:  Skipping main.cvd, local version (60) is newer than advertised version (59)
```

--------------------------------

### Start MirrorRequestHandler HTTP Server

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/MirrorRequestHandler.md

This snippet demonstrates how to initialize and run the MirrorRequestHandler to serve files from the current directory over HTTP on port 8000. Ensure the MirrorRequestHandler class and HTTPServer are imported.

```python
from http.server import HTTPServer
from cvdupdate.__main__ import MirrorRequestHandler

handler = MirrorRequestHandler
handler.protocol_version = 'HTTP/1.0'
httpd = HTTPServer(('', 8000), MirrorRequestHandler)
httpd.serve_forever()
```

--------------------------------

### Serve Database Mirror HTTP Server

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/cli-reference.md

Starts an HTTP server to serve the database directory. The PORT argument specifies the port number; 0 selects a random available port. Use this for testing database mirroring.

```bash
cvd serve [OPTIONS] [PORT]
```

```bash
$ cvd serve
2024-06-22 14:30:45 - INFO:  Serving up ~/.cvdupdate/database on localhost:8000...
```

```bash
$ cvd serve 9000  # Custom port
2024-06-22 14:30:45 - INFO:  Serving up ~/.cvdupdate/database on localhost:9000...
```

```bash
$ cvd serve 0  # Random port
2024-06-22 14:30:45 - INFO:  Serving up ~/.cvdupdate/database on localhost:45678...
```

```bash
$ cvd serve 8000 --update-interval-seconds 3600  # Update every hour
2024-06-22 14:30:45 - INFO:  Updating the database every 3600 seconds
2024-06-22 14:30:45 - INFO:  Serving up ~/.cvdupdate/database on localhost:8000...
```

--------------------------------

### Docker with Custom Schedule and Logging

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/configuration.md

This example demonstrates how to run the cvdupdate Docker container with a custom cron schedule (daily at midnight) and enable file logging by setting environment variables.

```bash
# Custom schedule (daily at midnight) and enable logging
docker run -d \
  -v "$(pwd)/database:/cvdupdate/database" \
  -v "$(pwd)/logs:/cvdupdate/logs" \
  -e CRON='0 0 * * *' \
  -e ENABLE_LOGS=true \
  cvdupdate:latest
```

--------------------------------

### Get cvdupdate help

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Access help information for any cvd command using the --help option.

```bash
cvd --help
```

--------------------------------

### Start cvdupdate Server and Test Access

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/MirrorRequestHandler.md

Starts the cvdupdate server on port 8000 and then uses curl to test various access scenarios including secure access, protected file access, directory listing, and range requests.

```bash
# Terminal 1: Start cvdupdate server
cvd serve 8000

# Terminal 2: Test secure access
$ curl http://localhost:8000/main.cvd
# Returns 200 OK with file content

$ curl http://localhost:8000/.state.json
# Returns 404 Not Found (protected)

$ curl http://localhost:8000/
# Returns HTML directory listing without dotfiles

$ curl -I http://localhost:8000/main.cvd
# Returns headers only (HEAD request)

$ curl -r 0-99 http://localhost:8000/main.cvd
# Returns first 100 bytes (Range request)
```

--------------------------------

### Example DNS TXT Record Response

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/types.md

An example of a DNS TXT record response, indicating specific versions for ClamAV databases. This format is used to quickly check for the latest database versions.

```text
"0:60:2847:0:0:0:0:331"
```

--------------------------------

### Serve CVD Definitions for Testing

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/OVERVIEW.md

Starts a local HTTP server to serve virus definition files, useful for testing purposes. Specify the port number.

```bash
# Serve for testing
cvd serve 8000
```

--------------------------------

### CVDUpdate Library Usage

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/OVERVIEW.md

Example of how to use the CVDUpdate class from the library to perform a database update.

```APIDOC
## Library Usage

### Initialize CVDUpdate
```python
from cvdupdate.cvdupdate import CVDUpdate
updater = CVDUpdate()
```

### Perform Database Update
```python
updater.db_update()
```
```

--------------------------------

### Schedule cvdupdate with cron

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Example cron job entry to schedule daily updates for cvdupdate. Ensure you use the full path to the 'cvd' executable.

```bash
30 */4 * * * /home/username/.local/bin/cvd update >/dev/null 2>&1
```

--------------------------------

### Full CLI Example with AliasedGroup

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/AliasedGroup.md

Demonstrates the integration of `AliasedGroup` into the main CLI structure, including registering commands with aliases like 'ls' for 'list' and 's' for 'status'.

```python
@click.group(
    cls=AliasedGroup,
    epilog=Fore.BLUE + __doc__ + ...
)
def cli():
    pass

@cli.command("list", aliases=["ls"])
def db_list(config, verbose, use_json):
    """List the DB names found in the database directory."""
    pass

@cli.command("status", aliases=["s"])
def db_status(config, verbose, use_json, db):
    """Show status of one or all databases."""
    pass
```

--------------------------------

### Testing Cvdupdate Server with FreshClam

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/cli-reference.md

Demonstrates how to configure and test FreshClam to use a locally served cvdupdate database mirror. This involves starting the cvd serve command and then modifying the FreshClam configuration.

```bash
# Terminal 1: Start server
cvd serve 8000
```

```bash
# Terminal 2: Configure FreshClam
# Edit /usr/local/etc/freshclam.conf
# Replace: DatabaseMirror database.clamav.net
# With: DatabaseMirror http://localhost:8000
```

```bash
# Terminal 2: Test FreshClam
freshclam -v
```

--------------------------------

### Build Docker Compose Services

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Builds the Docker images defined in the docker-compose.yaml file. This is typically done before starting the services for the first time or after making changes to the Dockerfile.

```bash
docker compose build
```

--------------------------------

### Blocked Paths Example for MirrorRequestHandler

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/MirrorRequestHandler.md

Illustrates paths that MirrorRequestHandler will block, returning a 404 Not Found response. This includes direct dotfiles, nested dotfiles, and encoded dotfiles.

```text
GET /.state.json      → 404 Not Found
GET /.git/HEAD        → 404 Not Found
GET /%2egit/config    → 404 Not Found (decoded from %2e)
GET /.hidden/file.txt → 404 Not Found
```

--------------------------------

### Update Specific Database with Debug Mode

Source: https://github.com/cisco-talos/cvdupdate/blob/main/CHANGES.md

This example shows how to update a specific database while also enabling debug mode to inspect HTTP headers. This can be useful for troubleshooting updates for individual databases.

```bash
cvd update <specific database> -D
```

--------------------------------

### Serve Command with Update Interval

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/auto_updater.md

Example of how the `cvd serve` command internally uses the auto_updater module to keep databases fresh. This demonstrates the typical usage context for the auto_updater.

```python
from cvdupdate.__main__ import serve
from cvdupdate import auto_updater

# Internal flow in serve() command
updater = CVDUpdate(config=config, verbose=verbose)
auto_updater.start(update_interval_seconds)  # Start background thread
# Then serve HTTP on port 8000
```

--------------------------------

### Uninstall CVD-Update

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Removes the CVD-Update package if it is already installed. This is a prerequisite before installing in edit mode.

```bash
python3 -m pip uninstall cvdupdate
```

--------------------------------

### Start Background Database Updates

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/auto_updater.md

Spawns a background daemon thread to update databases at regular intervals. Set the interval to 0 or a negative value to disable automatic updates. The thread exits when the main process exits.

```python
from cvdupdate import auto_updater

# Start background updates every 3600 seconds (1 hour)
auto_updater.start(3600)
# Thread now runs in background

# Start without background updates
auto_updater.start(0)  # No thread spawned
```

--------------------------------

### Get Database Update Error Count

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/errors.md

Call the `db_update()` method to get the number of databases that failed to update. A return value of 0 indicates success.

```python
error_count = updater.db_update()
```

--------------------------------

### Programmatic Configuration with Defaults

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/configuration.md

Initialize CVDUpdate as a library using default configuration settings.

```python
from cvdupdate.cvdupdate import CVDUpdate

# Minimal: use defaults
updater = CVDUpdate()
```

--------------------------------

### Install CVD-Update in Edit Mode

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Installs CVD-Update in editable mode using pip. This allows changes in your local clone to be immediately reflected when running the cvdupdate/cvd commands.

```bash
python3 -m pip install -e --user ./cvdupdate
```

--------------------------------

### Add Custom Database via CLI

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/README.md

Add a custom signature database from a specified URL.

```bash
cvd add custom.ndb https://example.com/custom.ndb
```

--------------------------------

### Initialize CVDUpdate with Custom Configuration

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/README.md

Create an instance of the CVDUpdate class with specific settings for database directory, nameservers, and verbosity.

```python
from cvdupdate.cvdupdate import CVDUpdate

updater = CVDUpdate(
    dbs_directory="/path/to/databases",
    nameservers="8.8.8.8,8.8.4.4",
    verbose=True
)
```

--------------------------------

### Serve Databases Locally

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Utilize the '--serve' feature to host the current database directory on http://localhost for testing.

```bash
# This command is conceptual and not directly executable from the text, but describes the functionality.
# Example of how to test with FreshClam:
# DatabaseMirror http://localhost:8000
```

--------------------------------

### Serve database directory locally

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Run this command to serve the database directory on http://localhost:8000 for testing with FreshClam. The port can be changed or set to 0 to pick a random available port.

```bash
cvd serve
```

--------------------------------

### Library Entry Point

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/OVERVIEW.md

To use CVDUpdate as a library, import the CVDUpdate class and instantiate it to perform database updates.

```python
from cvdupdate.cvdupdate import CVDUpdate
updater = CVDUpdate()
updater.db_update()
```

--------------------------------

### Display Current Configuration

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/cli-reference.md

View the current configuration settings. Use the --json flag for machine-readable output.

```bash
cvd config show
```

```bash
cvd config show --json
```

--------------------------------

### State File Schema Structure

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/types.md

Defines the overall structure of the state.json file, including the unique identifier for the installation and a dictionary for database configurations.

```python
{
    "uuid": str,  # Unique identifier for this installation (UUID4 format)
    "dbs": {      # Dictionary of database name → configuration record
        "main.cvd": {...},
        "daily.cvd": {...},
        "bytecode.cvd": {...},
        # Additional custom databases...
    }
}
```

--------------------------------

### Instantiate CVDUpdate with Custom Config and Verbose Logging

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/CVDUpdate.md

Create a CVDUpdate instance specifying a custom configuration file path and enabling verbose logging for detailed output.

```python
# Create with custom config path and verbose logging
updater = CVDUpdate(config="/etc/cvdupdate/config.json", verbose=True)
```

--------------------------------

### Instantiate CVDUpdate with Default Configuration

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/CVDUpdate.md

Create a CVDUpdate instance using default settings. This is useful for basic usage where custom configurations are not needed.

```python
from cvdupdate.cvdupdate import CVDUpdate

# Create instance with default configuration
updater = CVDUpdate()
```

--------------------------------

### Test FreshClam Configuration with Local Mirror

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/OVERVIEW.md

This snippet demonstrates how to test your FreshClam configuration by running a local cvdupdate server and pointing FreshClam to it.

```bash
# Terminal 1: Start server
cvd serve 8000

# Terminal 2: Configure and test FreshClam
# Edit freshclam.conf: DatabaseMirror http://localhost:8000
freshclam -v
```

--------------------------------

### Python: Handle Config Directory Creation Error

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/errors.md

This snippet demonstrates how to handle a scenario where the configuration directory cannot be created due to permission errors. It shows the initialization of CVDUpdate with a specific config path.

```python
# Attempt to use config in read-only directory
updater = CVDUpdate(config="/etc/cvdupdate/config.json")
# If /etc owned by root and user lacks permissions: exception raised
```

--------------------------------

### Programmatic Configuration with Overridden Settings

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/configuration.md

Initialize CVDUpdate programmatically, overriding specific configuration settings like database directory, DNS servers, and logging.

```python
# Override specific settings
updater = CVDUpdate(
    dbs_directory="/var/www/html/clamav",
    nameservers="8.8.8.8,8.8.4.4",
    max_retries=5,
    logs_enabled=True,
    logs_directory="/var/log/cvdupdate"
)
```

--------------------------------

### Initialize CVDUpdate Python Library

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/OVERVIEW.md

Creates an instance of the CVDUpdate class, specifying the database directory and nameservers. Required before performing updates.

```python
from cvdupdate.cvdupdate import CVDUpdate

# Create instance
updater = CVDUpdate(
    dbs_directory="/path/to/databases",
    nameservers="8.8.8.8,8.8.4.4"
)
```

--------------------------------

### Python: Handle Database File Deletion Error

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/errors.md

Shows how to handle errors when deleting a database file during cleanup, which might be due to permissions or the file being locked. This is a conceptual example.

```python
# Example scenario: Attempting cleanup that might fail
# updater.cleanup_database()
# If database file is locked or permissions are wrong: exception raised
```

--------------------------------

### Show Configuration in JSON Format

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/configuration.md

Retrieve the current CVDUpdate configuration in JSON format using the --json flag.

```bash
cvd config show --json
```

--------------------------------

### List all configured databases

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/cli-reference.md

Use 'cvd list' to display all configured database names. The --json flag outputs the list as a JSON array.

```bash
cvd list [OPTIONS]
```

```bash
$ cvd list
main.cvd
daily.cvd
bytecode.cvd
```

```bash
$ cvd list --json
[
    "main.cvd",
    "daily.cvd",
    "bytecode.cvd"
]
```

```bash
cvd ls  # Same as cvd list
```

--------------------------------

### Show Current Configuration

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/configuration.md

Display the current CVDUpdate configuration in a human-readable format.

```bash
cvd config show
```

--------------------------------

### list_directory

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/MirrorRequestHandler.md

Generates a directory listing while securely hiding dotfiles and dotdirectories. It temporarily replaces os.listdir to filter out entries starting with a dot before calling the parent class's list_directory method.

```APIDOC
## GET /

### Description
Generate directory listing while hiding dotfiles.

### Method
GET

### Endpoint
/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
HTTP response (generated by parent class)

#### Response Example
Browser request to `http://localhost:8000/` shows:
```
Index of /
[ICO]       Name                    Last modified      Size  Description
[PARENTDIR] Parent Directory        -                 -     
[TXT]       main.cvd               2024-06-22        50M   
[TXT]       daily.cvd              2024-06-22        100M  
[TXT]       bytecode.cvd           2024-06-22        10M   
[TXT]       dns.txt                2024-06-22        1K
```

Hidden entries (.state.json, .git if present) are not shown.
```

--------------------------------

### Python: Handle Unrecognized Database Extension

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/errors.md

Shows how the system handles adding a database with an unrecognized extension. This is a warning and does not prevent operation. The code snippet is conceptual.

```python
# Conceptual example of adding a database with an unrecognized extension
# updater.config_add_db(db_path="/path/to/database.xyz")
# Warning is logged, but operation continues.
```

--------------------------------

### Add or Update Database Configuration

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/CVDUpdate.md

Use `config_add_db` to add a new database to the update list or change the download URL for an existing one. Set `override=True` to force an update of the URL.

```python
updater = CVDUpdate()

# Add new database
if updater.config_add_db("custom.ndb", "https://example.com/custom.ndb"):
    print("Database added successfully")

# Update URL for existing database
if updater.config_add_db("daily.cvd", "https://mirror.example.com/daily.cvd", override=True):
    print("URL updated")
```

--------------------------------

### Inspect Database and Log Directories

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Examine the contents of the database and log directories to verify downloaded files and log entries.

```bash
ls ~/.cvdupdate/database
```

```bash
ls ~/.cvdupdate/logs
```

```bash
cat ~/.cvdupdate/logs/*
```

--------------------------------

### Usage of MirrorRequestHandler in cvd serve

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/MirrorRequestHandler.md

Demonstrates how MirrorRequestHandler is used within the 'cvd serve' command to set up a local HTTP server for serving CVD databases. It includes starting background updates and logging server information.

```python
from cvdupdate.__main__ import MirrorRequestHandler
from http.server import HTTPServer

def serve(port, config, verbose, update_interval_seconds):
    m = CVDUpdate(config=config, verbose=verbose)
    os.chdir(str(m.dbs_directory))
    
    # Start background updates if requested
    auto_updater.start(update_interval_seconds)
    
    # Create secure HTTP server
    MirrorRequestHandler.protocol_version = 'HTTP/1.0'
    httpd = HTTPServer(('', port), MirrorRequestHandler)
    actual_port = httpd.server_address[1]
    
    m.logger.info(f"Serving up {m.dbs_directory} on localhost:{actual_port}..." )
    httpd.serve_forever()
```

--------------------------------

### Configure HTTP/HTTPS Proxy with Environment Variables

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/configuration.md

Set standard http_proxy and https_proxy environment variables to route cvdupdate traffic through a proxy server.

```bash
export http_proxy="http://proxy.example.com:3128"
export https_proxy="http://proxy.example.com:3128"
cvd update
```

--------------------------------

### Programmatic Configuration with Custom Config Path

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/configuration.md

Initialize CVDUpdate programmatically, specifying a custom path to the configuration file.

```python
# Custom configuration directory
updater = CVDUpdate(config="/etc/cvdupdate/config.json")
```

--------------------------------

### Instantiate CVDUpdate with Custom Database Directory and Nameservers

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/CVDUpdate.md

Create a CVDUpdate instance specifying a custom directory for databases and providing custom DNS nameservers for version checks.

```python
# Create with custom database directory and nameserver
updater = CVDUpdate(dbs_directory="/var/www/html/clamav", nameservers="8.8.8.8,8.8.4.4")
```

--------------------------------

### format_commands Method

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/AliasedGroup.md

Formats the command list for help display, including aliases inline. This method enhances user experience by showing available aliases.

```APIDOC
## format_commands Method

```python
def format_commands(self, ctx, formatter)
```

Format command list for help display with aliases inline.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| ctx | click.Context | Yes | Click context |
| formatter | click.HelpFormatter | Yes | Formatter for output |

**Returns:** None (updates formatter)

**Behavior:**
- Lists each primary command with help text
- Appends aliases in parentheses if present
- Hides hidden commands
- Skips display if no commands available

**Example help output:**

```
Commands:
  list (ls)      List the DB names found in the database directory.
  status (s)     Show status of one or all databases.
  update (u)     Update the DBs from the internet.
  add            Add a db to the list of known DBs.
  remove (rm)    Remove a db from the list of known DBs.
  config (cf)    Commands to configure.
  clean (cl)     Commands to clean up.
  serve          Serve up the database directory.
```
```

--------------------------------

### Basic Docker Usage

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/configuration.md

This snippet shows the basic command to run the cvdupdate Docker container with a volume mount for the database. It uses the default cron schedule.

```bash
# Basic usage with default cron (every 4 hours)
docker run -d \
  -v "$(pwd)/database:/cvdupdate/database" \
  cvdupdate:latest
```

--------------------------------

### Deploy CVDUpdate using Docker

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/OVERVIEW.md

Run cvdupdate in a Docker container, mounting a local directory for database storage and configuring update frequency via an environment variable.

```bash
docker run -d \
  -v "$(pwd)/database:/cvdupdate/database" \
  -e CRON='0 */6 * * *' \
  cvdupdate:latest
```

--------------------------------

### Manage Custom Databases with Python

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/OVERVIEW.md

Adds a custom virus definition database from a URL and lists all managed databases. Useful for integrating external definitions.

```python
# Manage databases
updater.config_add_db("custom.ndb", "https://example.com/custom.ndb")
updater.db_list()
```

--------------------------------

### Build the CVDUpdate Docker Image

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Builds the Docker image from the current directory. The image is tagged as 'cvdupdate:latest'.

```bash
docker build . --tag cvdupdate:latest
```

--------------------------------

### Programmatic Configuration for Verbose Logging

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/configuration.md

Enable verbose logging when initializing CVDUpdate programmatically by setting the 'verbose' parameter to True.

```python
# Enable verbose logging
updater = CVDUpdate(verbose=True)
```

--------------------------------

### Configure Custom Database Directory via CLI

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/README.md

Set a custom directory for storing ClamAV signature databases using this command.

```bash
cvd config set --dbs-directory /var/www/clamav
```

--------------------------------

### List Available Databases

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Execute the 'cvd list' command to retrieve a list of all available database names.

```bash
cvd list
```

--------------------------------

### cvdupdate Data Flow

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/OVERVIEW.md

Illustrates the data flow from user command to database directory management within the cvdupdate tool.

```text
User Command
    ↓
CLI (click.Group via __main__.py)
    ↓
CVDUpdate Instance (cvdupdate.py)
    ├─ Load/Save Config (config.json, state.json)
    ├─ Query DNS (current.cvd.clamav.net TXT records)
    ├─ Download Files (HTTP with If-Modified-Since)
    ├─ Manage CDIFFs (patch files)
    └─ Logging (file and console)
    ↓
Database Directory
    ├─ .cvd files (main, daily, bytecode, custom)
    ├─ .cdiff files (patches)
    ├─ .sign files (signatures)
    └─ dns.txt (last known DNS record)
```

--------------------------------

### command Method

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/AliasedGroup.md

Decorator to register a command with optional aliases. Aliases are displayed inline in the help text.

```APIDOC
## command Method

```python
def command(self, *args, aliases=None, **kwargs)
```

Decorator to register a command with optional aliases.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| *args | tuple | No | () | Passed to parent Click group |
| aliases | list[str] | No | None | List of alias names for this command |
| **kwargs | dict | No | {} | Passed to parent Click group |

**Returns:** Decorator function.

**Implementation:** 
- Registers command with Click
- If aliases provided: maps each alias to command name
- Updates reverse mapping for help display

**Example:**

```python
from cvdupdate.__main__ import AliasedGroup
import click

@click.group(cls=AliasedGroup)
def cli():
    pass

@cli.command("status", aliases=["s"])
def db_status():
    """Show database status."""
    pass

# Now both work:
# cvd status
# cvd s
```
```

--------------------------------

### Add Custom Database via Python Library

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/README.md

Use this method to add a custom signature database to the configuration, specifying its name and URL.

```python
# Add a database
updater.config_add_db("custom.ndb", "https://example.com/custom.ndb")
```

--------------------------------

### Registering a Command with Aliases

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/AliasedGroup.md

Use the `command` decorator to register a new command with optional aliases. Aliases are provided as a list of strings.

```python
from cvdupdate.__main__ import AliasedGroup
import click

@click.group(cls=AliasedGroup)
def cli():
    pass

@cli.command("status", aliases=["s"])
def db_status():
    """Show database status."""
    pass
```

--------------------------------

### Use Config Alias

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/cli-reference.md

The 'cf' alias provides a shorter way to access configuration commands.

```bash
cvd cf set --dbs-directory /var/www/clamav  # Same as cvd config set
```

```bash
cvd cf show  # Same as cvd config show
```

--------------------------------

### Enable File Logging with Custom Directory

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/configuration.md

Configure CVDUpdate to enable file logging and specify a custom directory for log files.

```bash
cvd config set --logs-enabled --logs-directory /var/log/cvdupdate
```

--------------------------------

### Handle CVDUpdate Initialization Errors

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/errors.md

Catch common exceptions like FileNotFoundError, PermissionError, or generic Exceptions when initializing CVDUpdate with an invalid configuration path.

```python
from cvdupdate.cvdupdate import CVDUpdate

try:
    updater = CVDUpdate(config="/invalid/path/config.json")
except (FileNotFoundError, PermissionError, Exception) as e:
    print(f"Failed to initialize: {e}")
```

--------------------------------

### Set CVD-Update Configuration Options

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Configure CVD-Update settings like database directory and log enablement using 'cvd config set'.

```bash
# e.g. point databases at your web root and keep the state file alongside it
cvd config set --dbs-directory /var/www/html/clamav --logs-enabled
```

--------------------------------

### Configure cvdupdate databases directory

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Customize the directory where cvdupdate stores downloaded databases.

```bash
cvd config set --dbs-directory <your www path>
```

--------------------------------

### Programmatic Configuration: Preserve Existing Log Rotation Setting

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/configuration.md

Use 'None' when initializing CVDUpdate programmatically to preserve the existing log rotation configuration without creating a new file.

```python
# Note: False and None have different meanings
# False preserves existing config value
# True/False sets the value
# Use None to preserve existing config (doesn't create file yet)
updater = CVDUpdate(logs_rotate=None)  # Preserves current setting
```

--------------------------------

### Formatting Command List with Aliases

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/AliasedGroup.md

The `format_commands` method is responsible for generating the help text output, displaying primary command names along with their aliases in parentheses.

```python
def format_commands(self, ctx, formatter)
```

--------------------------------

### Configure FreshClam to use local database mirror

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Modify your freshclam.conf file to point to your locally served database mirror. This is for testing purposes.

```ini
DatabaseMirror http://localhost:8000
```

--------------------------------

### Combine Multiple Configuration Settings

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/configuration.md

Apply multiple configuration settings simultaneously using the 'cvd config set' command.

```bash
cvd config set --dbs-directory /var/www/clamav --logs-enabled --nameservers 208.67.222.222
```

--------------------------------

### Set Configuration Options

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/cli-reference.md

Use this command to set various configuration options for cvdupdate. You can specify directories, nameservers, and logging behavior.

```bash
cvd config set --dbs-directory /var/www/html/clamav --logs-enabled
```

```bash
cvd config set --nameservers 8.8.8.8,8.8.4.4 --max-retries 5
```

```bash
cvd config set --no-cdiffs-rotate  # Keep all CDIFFs
```

--------------------------------

### Add a new database to the update list

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/cli-reference.md

Use this command to add a new database to the cvdupdate configuration. Specify the database filename and the URL from which it should be downloaded. The --override option can be used to update the URL if the database already exists.

```bash
cvd add custom.ndb https://example.com/custom.ndb
2024-06-22 14:30:45 - INFO:  Added custom.ndb (https://example.com/custom.ndb) to DB list.
2024-06-22 14:30:45 - INFO:  custom.ndb will be downloaded next time you run `cvd update` or `cvd update custom.ndb`
```

```bash
cvd add custom.ndb https://mirror.example.com/custom.ndb
2024-06-22 14:30:45 - INFO:  Cannot add custom.ndb, it is already in our list.
2024-06-22 14:30:45 - INFO:  Hint: Try `cvd status custom.ndb` for more information, use `cvd add --override custom.ndb <url>` to update the URL.
```

```bash
cvd add --override custom.ndb https://mirror.example.com/custom.ndb
2024-06-22 14:30:45 - INFO:  Updated URL for custom.ndb: https://example.com/custom.ndb -> https://mirror.example.com/custom.ndb
```

--------------------------------

### Add a New Database

Source: https://github.com/cisco-talos/cvdupdate/blob/main/README.md

Use 'cvd add' to include a new database, providing its name and URL. The URL can be overridden if the database already exists.

```bash
cvd add linux.cvd https://database.clamav.net/linux.cvd
```

```bash
cvd add --override linux.cvd https://mirror.example.com/linux.cvd
```

--------------------------------

### db_show

Source: https://github.com/cisco-talos/cvdupdate/blob/main/_autodocs/api-reference/CVDUpdate.md

Displays detailed information for a specific database by its filename. Returns true if the database is found and its information is logged, false otherwise.

```APIDOC
## db_show

### Description
Show detailed information for a specific database.

### Method
`db_show(self, name: str) -> bool`

### Parameters
#### Arguments
- **name** (str) - Required - Database filename to query.

### Returns
True if database found and shown, False if not found.

### Example
```python
updater = CVDUpdate()
if updater.db_show("daily.cvd"):
    print("Database found and information logged")
else:
    print("Database not found")
```
```