StrikePackageGPT/BIDIRECTIONAL_CAPTURE.md

Bidirectional Command Capture

Overview

StrikePackageGPT now supports bidirectional command capture, enabling commands run directly in the Kali container to be automatically captured and displayed in the dashboard alongside commands executed via the UI/API.

This feature is perfect for advanced users who prefer command-line interfaces but still want visual tracking and historical reference.

How It Works

┌─────────────────────────────────────────────────────────────┐
│                    Two-Way Flow                              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Dashboard UI → HackGPT API → Kali Executor → Kali Container│
│       ↓                                           ↑          │
│  Stored in scan_results  ←────────────────────────          │
│       ↓                                                      │
│  Displayed in Dashboard History                             │
│                                                              │
│  Direct Shell → Command Logger → JSON Files → API Sync      │
│                      ↓                           ↑          │
│              /workspace/.command_history    Auto-Import     │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Features

Automatic Logging

• All commands run in interactive bash sessions are automatically logged
• Command metadata captured: timestamp, user, working directory, exit code, duration
• Full stdout/stderr captured for commands run with capture wrapper

Unified History

• Commands from both sources (UI and direct shell) appear in the same history
• Consistent format and parsing across all command sources
• Network visualization includes manually-run scans

Real-Time Sync

• API endpoint to pull latest captured commands
• Background sync every 30 seconds (configurable)
• Manual sync available via /commands/sync endpoint

Usage

Option 1: Automatic Logging (All Commands)

When you connect to the Kali container, command logging is enabled automatically:

docker exec -it strikepackage-kali bash

Now run any security tool:

nmap -sV 192.168.1.0/24
sqlmap -u "http://example.com?id=1"
nikto -h http://example.com

These commands are logged with basic metadata. Full output capture requires Option 2.

Option 2: Explicit Capture (With Full Output)

Use the capture command prefix for full output capture:

docker exec -it strikepackage-kali bash
capture nmap -sV 192.168.1.0/24
capture gobuster dir -u http://example.com -w /usr/share/wordlists/dirb/common.txt

This captures:

• Full stdout and stderr
• Exit codes
• Execution duration
• All command metadata

View Recent Commands

Inside the container:

recent  # Shows last 10 captured commands

Sync to Dashboard

Commands are automatically synced to the dashboard. To manually trigger a sync:

curl -X POST http://localhost:8001/commands/sync

API Endpoints

Get Captured Commands

GET /commands/captured?limit=50&since=2025-12-03T00:00:00Z

Returns commands captured from interactive sessions.

Response:

{
  "commands": [
    {
      "command_id": "abc-123-def",
      "command": "nmap -sV 192.168.1.0/24",
      "timestamp": "2025-12-03T14:30:00Z",
      "completed_at": "2025-12-03T14:35:00Z",
      "status": "completed",
      "exit_code": 0,
      "duration": 300,
      "stdout": "... nmap output ...",
      "stderr": "",
      "user": "root",
      "working_dir": "/workspace",
      "source": "capture_wrapper"
    }
  ],
  "count": 1,
  "imported_to_history": true
}

Sync Commands to History

POST /commands/sync

Imports all captured commands into the unified scan history, making them visible in the dashboard.

Response:

{
  "status": "synced",
  "imported_count": 15,
  "message": "All captured commands are now visible in dashboard history"
}

View Unified History

GET /scans

Returns all commands from both sources (UI and direct shell).

Dashboard Integration

Viewing Captured Commands

1. Scan History Tab: Shows all commands (UI + captured)
2. Network Map: Includes hosts discovered via manual scans
3. Timeline View: Shows when commands were executed
4. Filter by Source: Filter to show only manually-run or UI-run commands

Visual Indicators

• 🔷 UI Commands: Blue indicator
• 🔶 Manual Commands: Orange indicator with "Interactive Shell" badge
• ⚡ Running: Animated indicator
• ✅ Completed: Green checkmark
• ❌ Failed: Red X with error details

Configuration

Enable/Disable Automatic Logging

To disable automatic logging in new shell sessions:

# Inside container
echo 'DISABLE_AUTO_LOGGING=1' >> ~/.bashrc

Change Log Directory

Set a custom log directory:

# In docker-compose.yml or .env
COMMAND_LOG_DIR=/custom/path/.command_history

Sync Interval

Configure auto-sync interval (default: 30 seconds):

# In HackGPT API configuration
COMMAND_SYNC_INTERVAL=60  # seconds

Technical Details

Storage Format

Commands are stored as JSON files in /workspace/.command_history/:

{
  "command_id": "unique-uuid",
  "command": "nmap -sV 192.168.1.1",
  "timestamp": "2025-12-03T14:30:00Z",
  "completed_at": "2025-12-03T14:35:00Z",
  "user": "root",
  "working_dir": "/workspace",
  "source": "capture_wrapper",
  "status": "completed",
  "exit_code": 0,
  "duration": 300,
  "stdout": "...",
  "stderr": ""
}

Command Logger (command_logger.sh)

• Hooks into PROMPT_COMMAND for automatic logging
• Filters out basic commands (cd, ls, etc.)
• Lightweight metadata-only logging
• No performance impact on command execution

Capture Wrapper (capture)

• Full command wrapper for complete output capture
• Uses eval with output redirection
• Measures execution time
• Captures exit codes
• Saves results as JSON

API Integration

1. Kali Executor reads JSON files from /workspace/.command_history/
2. HackGPT API imports them into scan_results dict
3. Dashboard displays them alongside UI-initiated commands
4. Automatic deduplication prevents duplicates

Security Considerations

Command Whitelist

• Command logging respects the existing whitelist
• Only whitelisted tools are executed
• Malicious commands are blocked before logging

Storage Limits

• Log directory is size-limited (default: 10MB)
• Oldest logs are automatically purged
• Configurable retention period

Access Control

• Logs are stored in container-specific workspace
• Only accessible via API with authentication (when enabled)
• No cross-container access

Troubleshooting

Commands Not Appearing in Dashboard

1. Check logging is enabled:

   docker exec -it strikepackage-kali bash -c 'echo $PROMPT_COMMAND'
   

2. Verify log files are created:

   docker exec -it strikepackage-kali ls -la /workspace/.command_history/
   

3. Manually trigger sync:

   curl -X POST http://localhost:8001/commands/sync
   

Output Not Captured

• Use capture prefix for full output: capture nmap ...
• Check log file exists: ls /workspace/.command_history/
• Verify command completed: recent

Performance Issues

If logging causes slowdowns:

1. Disable for current session:

   unset PROMPT_COMMAND
   

2. Increase sync interval:

   # In .env
   COMMAND_SYNC_INTERVAL=120
   

3. Clear old logs:

   curl -X DELETE http://localhost:8001/captured_commands/clear
   

Examples

Example 1: Network Reconnaissance

# In Kali container
docker exec -it strikepackage-kali bash

# Run discovery scan (automatically logged)
nmap -sn 192.168.1.0/24

# Run detailed scan with full capture
capture nmap -sV -sC -p- 192.168.1.100

# View in dashboard
# → Go to Scan History
# → See both commands with full results
# → View in Network Map

Example 2: Web Application Testing

# Directory bruteforce
capture gobuster dir -u http://target.com -w /usr/share/wordlists/dirb/common.txt

# SQL injection testing
capture sqlmap -u "http://target.com?id=1" --batch --dbs

# Vulnerability scanning
capture nikto -h http://target.com

# All results appear in dashboard history

Example 3: Wireless Auditing

# Put adapter in monitor mode
capture airmon-ng start wlan0

# Scan for networks
capture airodump-ng wlan0mon

# Results visible in dashboard with timestamps

Advantages

For Advanced Users

• ✅ Use familiar command-line interface
• ✅ Full control over tool parameters
• ✅ Faster than clicking through UI
• ✅ Still get visual tracking and history

For Teams

• ✅ All team member activity captured
• ✅ Unified view of all scan activity
• ✅ Easy to review what was run
• ✅ Share results without screenshots

For Reporting

• ✅ Complete audit trail
• ✅ Timestamp all activities
• ✅ Include in final reports
• ✅ Demonstrate thoroughness

Comparison

Feature	UI-Only	Bidirectional
Run commands via dashboard	✅	✅
Run commands via CLI	❌	✅
Visual history	✅	✅
Network map integration	✅	✅
Advanced tool parameters	Limited	Full
Speed for power users	Slow	Fast
Learning curve	Low	Medium

Future Enhancements

• Real-time streaming: See command output as it runs
• Collaborative mode: Multiple users see each other's commands
• Smart suggestions: AI suggests next commands based on results
• Template library: Save common command sequences
• Report integration: One-click add to PDF report

Support

For issues or questions:

• GitHub Issues: https://github.com/mblanke/StrikePackageGPT/issues
• Documentation: See FEATURES.md and INTEGRATION_EXAMPLE.md
• Examples: Check examples/ directory