Using bit-inspect¶

bit-inspect is a test information tool that helps you understand what tests are available, what they check, and how they're configured.

Overview¶

Use bit-inspect to:

List all available tests with descriptions
View detailed test metadata (author, version, date built)
Inspect configuration values loaded from TOML files
Check test status and run frequency
Debug test setup before running

Quick Start¶

# Set environment variables
export BIT_CONFIG_PATH=/etc/bit
export BIT_TEST_PATH=/usr/local/lib/bit_manager

# List all tests
bit-inspect

# Get details about a specific test
bit-inspect pbit_cpu_usage

Listing All Tests¶

Basic List¶

$ bit-inspect

cbit_cpu_usage: CPU utilization monitoring: Monitor CPU usage over 5 samples stays below 29%
cbit_disk_usage: Disk health monitoring: Continuous disk health monitoring
cbit_ethernet: Ethernet Monitoring: CBIT: Monitoring 2 network interfaces every 30s
cbit_memory_usage: Memory utilization test: Continuously monitor memory usage
pbit_cpu_usage: CPU utilization test: Check CPU usage is below 31% threshold
pbit_disk_usage: PBIT Disk Health Test: Comprehensive disk health test
pbit_ethernet: Ethernet Interface Status: PBIT: Auditing 2 network interfaces
pbit_memory_usage: Memory integrity test: Test memory availability, usage
...

Output Format:

test_name: Short description: Detailed description

Filtering Output¶

# Show only PBIT tests
bit-inspect | grep "^pbit_"

# Show only CBIT tests
bit-inspect | grep "^cbit_"

# Show only FBIT tests
bit-inspect | grep "^fbit_"

# Search for specific tests
bit-inspect | grep -i "disk"
bit-inspect | grep -i "network\|ethernet"
bit-inspect | grep -i "temperature\|thermal"

Counting Tests¶

# Count total tests
bit-inspect | wc -l

# Count by type
bit-inspect | grep "^pbit_" | wc -l  # PBIT count
bit-inspect | grep "^cbit_" | wc -l  # CBIT count
bit-inspect | grep "^fbit_" | wc -l  # FBIT count

Inspecting Specific Tests¶

Detailed Test Information¶

$ bit-inspect cbit_disk_usage

Details:
  Long-Name              Disk utilization test
  Author                 Ross Newman <[email protected]>
  Description            Check the disk is not nearing full
  Status                 NotRun

Plugin Details:
  Plugin Name            cbit_disk_usage
  Version                1.0.0
  Date Built             2025-12-08 01:42:11
  Module                 /usr/local/lib/bit_manager/libcbit_disk_usage.so
  Config File            /etc/bit/cbit_disk_usage.toml
  Run Frequency          Periodic(30s)

Config Details:
  disk
    +----(0) disk: "/dev/sda1"
    +----(0) threshold: 80
    +----(1) disk: "/dev/shm"
    +----(1) threshold: 80

  cbit_disk_usage
    +---- enabled: true
    +---- frequency: 30

Information Sections¶

Details Section: - Long-Name: Human-readable test name - Author: Test developer and contact - Description: What the test validates - Status: Current execution status (NotRun, Pass, Fail)

Plugin Details: - Plugin Name: Internal test identifier - Version: Test plugin version - Date Built: Compilation timestamp - Module: Path to .so file - Config File: Path to TOML configuration - Run Frequency: OneShot (PBIT) or Periodic (CBIT)

Config Details: - Shows all configuration values loaded from TOML - Hierarchical structure with arrays and nested values - Useful for verifying bit-learn output

Common Use Cases¶

Verify Test Installation¶

Check if all expected tests are available:

# Should show 52+ tests (21 PBIT + 21 CBIT + 9 FBIT + custom)
bit-inspect | wc -l

# Check specific test exists
bit-inspect | grep pbit_ethernet || echo "Test not found"

Check Configuration Values¶

Before running tests, verify configuration is correct:

# Check CPU threshold
bit-inspect pbit_cpu_usage | grep threshold

# Check disk thresholds
bit-inspect cbit_disk_usage | grep -A 10 "Config Details"

# Check network interfaces
bit-inspect pbit_ethernet | grep -A 20 "Config Details"

Debug Test Loading Issues¶

If a test won't load, inspect shows the error:

# Check module path
bit-inspect problematic_test | grep "Module:"

# Check config path
bit-inspect problematic_test | grep "Config File:"

# Verify files exist
TEST_SO=$(bit-inspect test_name | grep "Module:" | awk '{print $2}')
ls -l "$TEST_SO"

TEST_CFG=$(bit-inspect test_name | grep "Config File:" | awk '{print $3}')
ls -l "$TEST_CFG"

Compare PBIT vs CBIT Configuration¶

# View PBIT config
bit-inspect pbit_cpu_usage | grep -A 10 "Config Details"

# View corresponding CBIT config
bit-inspect cbit_cpu_usage | grep -A 10 "Config Details"

# See frequency difference
bit-inspect pbit_cpu_usage | grep "Run Frequency"
bit-inspect cbit_cpu_usage | grep "Run Frequency"

Find Tests by Author¶

# List all tests by a specific author
bit-inspect | while read line; do
    test_name=$(echo "$line" | cut -d: -f1)
    bit-inspect "$test_name" | grep -q "Author.*Newman" && echo "$test_name"
done

Generate Test Documentation¶

# Create a test catalog
for test in $(bit-inspect | cut -d: -f1); do
    echo "## $test"
    bit-inspect "$test" | grep "Description"
    echo ""
done > test_catalog.md

Understanding Test Status¶

Status Values¶

NotRun - Test hasn't been executed yet - Default state after loading - Shows in bit-inspect before running bit-manager

Pass - Test last execution succeeded - All checks passed - System meets requirements

Fail - Test last execution failed - Issue detected - Requires attention

Checking Test Status¶

# View status for specific test
bit-inspect pbit_cpu_usage | grep "Status:"

# After running tests, status updates
bit-manager -t pbit_cpu_usage -o
bit-inspect pbit_cpu_usage | grep "Status:"  # Should show Pass or Fail

Configuration Inspection¶

Understanding Config Output¶

Config section shows the TOML structure in tree format:

Config Details:
  section_name
    +---- key: value
    +----(0) array_item: value
    +----(1) array_item: value

Example: Whitelist Configuration¶

$ bit-inspect pbit_usb_whitelist | grep -A 30 "Config Details"

Config Details:
  device
    +----(0) device_name: "USB Hub"
    +----(0) vendor_id: "1d6b"
    +----(0) device_id: "0002"
    +----(1) device_name: "Keyboard"
    +----(1) vendor_id: "046d"
    +----(1) device_id: "c52b"
    +----(2) device_name: "Mouse"
    +----(2) vendor_id: "046d"
    +----(2) device_id: "c077"

Example: Threshold Configuration¶

$ bit-inspect pbit_memory_usage | grep -A 10 "Config Details"

Config Details:
  pbit_memory_usage
    +---- enabled: true
    +---- threshold: 90
    +---- swap_threshold: 50
    +---- min_available_mb: 512

Example: Interface Configuration¶

$ bit-inspect pbit_ethernet | grep -A 15 "Config Details"

Config Details:
  interface
    +----(0) name: "eth0"
    +----(0) expected_speed: 1000
    +----(0) expected_state: "up"
    +----(1) name: "eth1"
    +----(1) expected_speed: 1000
    +----(1) expected_state: "up"

Verifying Test Frequencies¶

Check CBIT Monitoring Intervals¶

# Quick frequency check
bit-inspect cbit_cpu_usage | grep "Run Frequency"
# Output: Run Frequency          Periodic(30s)

bit-inspect cbit_temperature | grep "Run Frequency"
# Output: Run Frequency          Periodic(60s)

bit-inspect cbit_usb_whitelist | grep "Run Frequency"
# Output: Run Frequency          Periodic(5s)

List All CBIT Frequencies¶

#!/bin/bash
echo "CBIT Test Frequencies:"
echo "====================="
for test in $(bit-inspect | grep "^cbit_" | cut -d: -f1); do
    freq=$(bit-inspect "$test" | grep "Run Frequency" | awk '{print $3}')
    printf "%-30s %s\n" "$test" "$freq"
done

Output:

CBIT Test Frequencies:
=====================
cbit_cpu_usage                 Periodic(30s)
cbit_disk_usage                Periodic(30s)
cbit_memory_usage              Periodic(30s)
cbit_temperature               Periodic(60s)
cbit_usb_whitelist             Periodic(5s)
...

Plugin Information¶

Module Path¶

The module path shows where the test plugin is loaded from:

bit-inspect pbit_cpu_usage | grep "Module:"
# Module: /usr/local/lib/bit_manager/libpbit_cpu_usage.so

Use cases: - Verify correct binary is loaded (debug vs release) - Check file permissions - Ensure plugin exists

Build Information¶

bit-inspect pbit_cpu_usage | grep -E "(Version|Date Built)"
# Version                1.0.0
# Date Built             2025-12-08 01:42:11

Use cases: - Verify you're running latest version - Check if plugins need rebuilding - Track deployment versions

Troubleshooting with bit-inspect¶

Test Not Listed¶

$ bit-inspect | grep my_test
# No output - test not found

Possible causes: 1. Plugin not compiled 2. Plugin not in BIT_TEST_PATH 3. Test name mismatch

Solutions:

# Check if .so exists
ls -l $BIT_TEST_PATH/libmy_test.so

# Rebuild test
cargo build -p my_test

# Verify path
echo $BIT_TEST_PATH

Config File Not Found¶

$ bit-inspect my_test
# Shows: Config File: /etc/bit/my_test.toml (missing)

Solution:

# Generate config
bit-learn

# Or create manually
nano /etc/bit/my_test.toml

Permission Errors¶

$ bit-inspect
# Error: Permission denied reading /usr/local/lib/bit_manager

Solutions:

# Run with sudo
sudo -E bit-inspect

# Or fix permissions
sudo chmod +rx /usr/local/lib/bit_manager
sudo chmod +r /usr/local/lib/bit_manager/*.so

Module Load Failures¶

If bit-inspect shows a test but bit-manager can't load it:

# Check dependencies
ldd $BIT_TEST_PATH/libmy_test.so

# Check for missing symbols
nm -D $BIT_TEST_PATH/libmy_test.so | grep create_test

Scripting with bit-inspect¶

Export Test List¶

# Create CSV of tests
bit-inspect | awk -F: '{print $1","$2","$3}' > tests.csv

Generate Test Matrix¶

#!/bin/bash
echo "| Test Name | Type | Frequency |"
echo "|-----------|------|-----------|"

for test in $(bit-inspect | cut -d: -f1); do
    type=$(echo "$test" | cut -d_ -f1)
    freq=$(bit-inspect "$test" | grep "Run Frequency" | awk '{print $3}')
    freq=${freq:-"OneShot"}
    echo "| $test | $type | $freq |"
done

Check Configuration Coverage¶

#!/bin/bash
# Verify all tests have configs
echo "Checking configuration coverage..."

for test in $(bit-inspect | cut -d: -f1); do
    config_file=$(bit-inspect "$test" | grep "Config File:" | awk '{print $3}')
    if [ ! -f "$config_file" ]; then
        echo "❌ Missing: $config_file"
    else
        echo "✓ $test"
    fi
done

Audit Test Versions¶

#!/bin/bash
echo "Test Version Audit"
echo "=================="

for test in $(bit-inspect | cut -d: -f1); do
    version=$(bit-inspect "$test" | grep "Version" | awk '{print $2}')
    date=$(bit-inspect "$test" | grep "Date Built" | awk '{print $3, $4}')
    echo "$test: v$version ($date)"
done | sort

Integration Examples¶

Pre-flight Check Script¶

#!/bin/bash
echo "BIT System Check"
echo "================"

# Check environment
if [ -z "$BIT_CONFIG_PATH" ]; then
    echo "❌ BIT_CONFIG_PATH not set"
    exit 1
fi

if [ -z "$BIT_TEST_PATH" ]; then
    echo "❌ BIT_TEST_PATH not set"
    exit 1
fi

# Count tests
total=$(bit-inspect | wc -l)
pbit=$(bit-inspect | grep "^pbit_" | wc -l)
cbit=$(bit-inspect | grep "^cbit_" | wc -l)
fbit=$(bit-inspect | grep "^fbit_" | wc -l)

echo "✓ Found $total tests:"
echo "  - $pbit PBIT tests"
echo "  - $cbit CBIT tests"
echo "  - $fbit FBIT tests"

# Check critical tests
critical="pbit_cpu_usage pbit_memory_usage pbit_disk_usage"
for test in $critical; do
    if bit-inspect | grep -q "^$test:"; then
        echo "✓ Critical test: $test"
    else
        echo "❌ Missing critical test: $test"
    fi
done

echo "✓ System ready"

Deployment Validation¶

#!/bin/bash
# Validate test deployment

echo "Validating BIT deployment..."

# Check all tests load
if ! bit-inspect > /dev/null 2>&1; then
    echo "❌ bit-inspect failed"
    exit 1
fi

# Check test count
expected=52  # 21 PBIT + 21 CBIT + 9 FBIT + 1 test_template
actual=$(bit-inspect | wc -l)

if [ "$actual" -lt "$expected" ]; then
    echo "⚠️  Expected $expected tests, found $actual"
fi

# Check configs exist
missing=0
for test in $(bit-inspect | cut -d: -f1); do
    config=$(bit-inspect "$test" | grep "Config File:" | awk '{print $3}')
    if [ ! -f "$config" ]; then
        echo "❌ Missing config: $config"
        ((missing++))
    fi
done

if [ $missing -eq 0 ]; then
    echo "✓ All configurations present"
    exit 0
else
    echo "❌ $missing configurations missing"
    exit 1
fi

Best Practices¶

Before Running Tests¶

# 1. Verify tests are loaded
bit-inspect | wc -l

# 2. Check critical test configs
bit-inspect pbit_cpu_usage | grep -A 5 "Config Details"
bit-inspect pbit_memory_usage | grep -A 5 "Config Details"
bit-inspect pbit_disk_usage | grep -A 10 "Config Details"

# 3. Verify CBIT frequencies are reasonable
for test in $(bit-inspect | grep "^cbit_" | cut -d: -f1); do
    bit-inspect "$test" | grep "Run Frequency"
done

After Configuration Changes¶

# 1. Regenerate configs
bit-learn

# 2. Inspect changed tests
bit-inspect pbit_ethernet | grep -A 10 "Config Details"

# 3. Test in one-shot mode
bit-manager -t pbit_ethernet -o

Regular Maintenance¶

# Monthly: Audit test versions
bit-inspect pbit_cpu_usage | grep "Date Built"

# Weekly: Verify no broken configs
for test in $(bit-inspect | cut -d: -f1); do
    bit-inspect "$test" > /dev/null || echo "Error: $test"
done

Next Steps¶

Running Tests - Execute tests with bit-manager
Test Types - Understand PBIT, CBIT, and FBIT
Configuration Guide - Edit test configs
Test Reference - Detailed test documentation

Edit this page on GitHub