scripts.js

Go to the documentation of this file.

/**
 * @file scripts.js
 * @module ScriptsRoutes
 * @description PowerShell ISE-style script library with per-tenant isolation. Manages script CRUD operations, execution on agents via WebSocket, execution history tracking, and agent script synchronization via manifest/download endpoints. Supports both tenant-specific and global scripts.
 * @see {@link ../services/websocketManager} for agent WebSocket connections
 * @see {@link ../db} for database connection
 * @apiDefine ScriptsGroup Scripts
 * @apiGroup Scripts
 * @apiHeader {string} Authorization Bearer token required.
 * @apiHeader {string} X-Tenant-ID Tenant context header required.
 * @apiError (Error 401) Unauthorized Missing or invalid token.
 * @apiError (Error 403) Forbidden Cannot modify global scripts or access unauthorized resources.
 * @apiError (Error 404) NotFound Script or execution not found.
 * @apiError (Error 409) Conflict Script with this name already exists.
 * @apiError (Error 500) ServerError Internal server error.
 */
const express = require('express');
const fs = require('fs');
const path = require('path');
const router = express.Router();
const wsManager = require('../services/websocketManager');
const pool = require('../db');
 
// ============================================
// SCRIPT CRUD OPERATIONS
// ============================================
 
/**
 * @api {get} /scripts/list List all scripts for current tenant
 * @apiName ListScripts
 * @apiGroup Scripts
 * @apiDescription Retrieve all scripts accessible to the current tenant (tenant-specific + global scripts). Results are ordered by global status first, then alphabetically by name.
 * @apiSuccess {object[]} scripts List of scripts.
 * @apiSuccess {string} scripts.script_id Script ID.
 * @apiSuccess {string} scripts.script_name Script name.
 * @apiSuccess {string} scripts.script_description Script description.
 * @apiSuccess {string} scripts.script_content Script content.
 * @apiSuccess {string} scripts.script_language Language (powershell, bash, etc.).
 * @apiSuccess {boolean} scripts.is_global Whether script is global (read-only).
 * @apiExample {curl} Example usage:
 *     curl -H "Authorization: Bearer <token>" -H "X-Tenant-ID: <id>" https://api.example.com/scripts/list
 */
router.get('/list', async (req, res) => {
  try {
    const tenant_id = req.headers['x-tenant-id'];
    
    // Handle "null" string as actual NULL
    const safeTenantId = (tenant_id === 'null' || !tenant_id) ? null : tenant_id;
    
    const result = await pool.query(`
      SELECT * FROM v_scripts_with_tenant
      WHERE (tenant_id = $1 OR is_global = true)
      ORDER BY is_global DESC, script_name ASC
    `, [safeTenantId]);
    
    res.json(result.rows);
  } catch (err) {
    console.error('[Scripts] List error:', err);
    res.status(500).json({ error: 'Failed to list scripts' });
  }
});
 
/**
 * @api {get} /scripts/manifest Get script manifest for agent sync
 * @apiName GetScriptManifest
 * @apiGroup Scripts
 * @apiDescription Returns a manifest of all scripts accessible to the current tenant with version info and hashes for agent synchronization. Used by agents to detect and download new or updated scripts.
 * @apiSuccess {object[]} scripts List of script manifest entries.
 * @apiSuccess {string} scripts.script_id Script ID.
 * @apiSuccess {string} scripts.script_name Script name.
 * @apiSuccess {string} scripts.script_hash SHA256 hash of script content.
 * @apiSuccess {number} scripts.version Script version.
 * @apiSuccess {number} scripts.file_size Script file size in bytes.
 * @apiSuccess {boolean} scripts.is_global Whether script is global.
 * @apiSuccess {number} count Total script count.
 * @apiSuccess {string} timestamp Manifest generation timestamp.
 * @apiExample {curl} Example usage:
 *     curl -H "Authorization: Bearer <token>" -H "X-Tenant-ID: <id>" https://api.example.com/scripts/manifest
 */
router.get('/manifest', async (req, res) => {
  try {
    const tenant_id = req.headers['x-tenant-id'];
    
    // Handle "null" string as actual NULL
    const safeTenantId = (tenant_id === 'null' || !tenant_id) ? null : tenant_id;
    
    // Get manifest entries for this tenant + global scripts
    const result = await pool.query(`
      SELECT 
        sm.script_id,
        sm.script_name,
        sm.script_hash,
        sm.version,
        sm.file_size,
        sm.is_global,
        sm.updated_at,
        s.script_language
      FROM script_manifest sm
      JOIN scripts s ON sm.script_id = s.script_id
      WHERE (sm.tenant_id = $1 OR sm.is_global = true)
      ORDER BY sm.is_global DESC, sm.script_name ASC
    `, [safeTenantId]);
    
    res.json({
      scripts: result.rows,
      count: result.rows.length,
      timestamp: new Date().toISOString()
    });
  } catch (err) {
    console.error('[Scripts] Manifest error:', err);
    res.status(500).json({ error: 'Failed to get script manifest' });
  }
});
 
/**
 * @api {get} /scripts/:script_id Get single script by ID
 * @apiName GetScript
 * @apiGroup Scripts
 * @apiDescription Retrieve a single script by ID. Script must be accessible to the current tenant (tenant-specific or global).
 * @apiParam {string} script_id Script ID.
 * @apiSuccess {object} script Script object.
 * @apiSuccess {string} script.script_id Script ID.
 * @apiSuccess {string} script.script_name Script name.
 * @apiSuccess {string} script.script_description Script description.
 * @apiSuccess {string} script.script_content Script content.
 * @apiSuccess {string} script.script_language Language (powershell, bash, etc.).
 * @apiSuccess {boolean} script.is_global Whether script is global.
 * @apiError (Error 404) NotFound Script not found or not accessible.
 * @apiExample {curl} Example usage:
 *     curl -H "Authorization: Bearer <token>" -H "X-Tenant-ID: <id>" https://api.example.com/scripts/abc123
 */
router.get('/:script_id', async (req, res) => {
  try {
    const { script_id } = req.params;
    const tenant_id = req.headers['x-tenant-id'];
    
    const result = await pool.query(`
      SELECT * FROM scripts
      WHERE script_id = $1 AND (tenant_id = $2 OR is_global = true)
    `, [script_id, tenant_id]);
    
    if (result.rows.length === 0) {
      return res.status(404).json({ error: 'Script not found' });
    }
    
    res.json(result.rows[0]);
  } catch (err) {
    console.error('[Scripts] Get error:', err);
    res.status(500).json({ error: 'Failed to get script' });
  }
});
 
/**
 * @api {post} /scripts/create Create new script
 * @apiName CreateScript
 * @apiGroup Scripts
 * @apiDescription Create a new script for the current tenant. Script name and content are required.
 * @apiParam {string} script_name Script name (unique per tenant).
 * @apiParam {string} script_content Script content/code.
 * @apiParam {string} [script_description] Script description.
 * @apiParam {string} [script_language=powershell] Script language (powershell, bash, python, etc.).
 * @apiSuccess {object} script Created script object.
 * @apiError (Error 400) BadRequest Script name and content are required.
 * @apiError (Error 409) Conflict Script with this name already exists.
 * @apiExample {curl} Example usage:
 *     curl -X POST -H "Authorization: Bearer <token>" -H "X-Tenant-ID: <id>" -d '{"script_name":"Install Updates","script_content":"Get-WindowsUpdate","script_language":"powershell"}' https://api.example.com/scripts/create
 */
router.post('/create', async (req, res) => {
  try {
    const { script_name, script_description, script_content, script_language } = req.body;
    const tenant_id = req.headers['x-tenant-id'];
    const user_id = req.user?.user_id; // From auth middleware
    
    if (!script_name || !script_content) {
      return res.status(400).json({ error: 'Script name and content are required' });
    }
    
    const result = await pool.query(`
      INSERT INTO scripts (tenant_id, script_name, script_description, script_content, script_language, created_by)
      VALUES ($1, $2, $3, $4, $5, $6)
      RETURNING *
    `, [tenant_id, script_name, script_description, script_content, script_language || 'powershell', user_id]);
    
    res.json(result.rows[0]);
  } catch (err) {
    if (err.code === '23505') { // Unique violation
      return res.status(409).json({ error: 'Script with this name already exists' });
    }
    console.error('[Scripts] Create error:', err);
    res.status(500).json({ error: 'Failed to create script' });
  }
});
 
/**
 * @api {put} /scripts/:script_id Update script
 * @apiName UpdateScript
 * @apiGroup Scripts
 * @apiDescription Update an existing tenant-specific script. Global scripts cannot be edited. Only provided fields will be updated.
 * @apiParam {string} script_id Script ID.
 * @apiParam {string} [script_name] New script name.
 * @apiParam {string} [script_description] New script description.
 * @apiParam {string} [script_content] New script content.
 * @apiParam {string} [script_language] New script language.
 * @apiSuccess {object} script Updated script object.
 * @apiError (Error 403) Forbidden Cannot edit global scripts.
 * @apiError (Error 404) NotFound Script not found or unauthorized.
 * @apiExample {curl} Example usage:
 *     curl -X PUT -H "Authorization: Bearer <token>" -H "X-Tenant-ID: <id>" -d '{"script_content":"Updated script content"}' https://api.example.com/scripts/abc123
 */
router.put('/:script_id', async (req, res) => {
  try {
    const { script_id } = req.params;
    const { script_name, script_description, script_content, script_language } = req.body;
    const tenant_id = req.headers['x-tenant-id'];
    
    // Can't edit global scripts
    const checkResult = await pool.query(`
      SELECT is_global FROM scripts WHERE script_id = $1
    `, [script_id]);
    
    if (checkResult.rows.length === 0) {
      return res.status(404).json({ error: 'Script not found' });
    }
    
    if (checkResult.rows[0].is_global) {
      return res.status(403).json({ error: 'Cannot edit global scripts' });
    }
    
    const result = await pool.query(`
      UPDATE scripts
      SET script_name = COALESCE($1, script_name),
          script_description = COALESCE($2, script_description),
          script_content = COALESCE($3, script_content),
          script_language = COALESCE($4, script_language),
          updated_at = NOW()
      WHERE script_id = $5 AND tenant_id = $6
      RETURNING *
    `, [script_name, script_description, script_content, script_language, script_id, tenant_id]);
    
    if (result.rows.length === 0) {
      return res.status(404).json({ error: 'Script not found or unauthorized' });
    }
    
    res.json(result.rows[0]);
  } catch (err) {
    console.error('[Scripts] Update error:', err);
    res.status(500).json({ error: 'Failed to update script' });
  }
});
 
/**
 * @api {delete} /scripts/:script_id Delete script
 * @apiName DeleteScript
 * @apiGroup Scripts
 * @apiDescription Delete a tenant-specific script. Global scripts cannot be deleted.
 * @apiParam {string} script_id Script ID.
 * @apiSuccess {boolean} success Operation success status.
 * @apiSuccess {string} message Status message.
 * @apiError (Error 403) Forbidden Cannot delete global scripts.
 * @apiError (Error 404) NotFound Script not found or unauthorized.
 * @apiExample {curl} Example usage:
 *     curl -X DELETE -H "Authorization: Bearer <token>" -H "X-Tenant-ID: <id>" https://api.example.com/scripts/abc123
 */
router.delete('/:script_id', async (req, res) => {
  try {
    const { script_id } = req.params;
    const tenant_id = req.headers['x-tenant-id'];
    
    // Can't delete global scripts
    const checkResult = await pool.query(`
      SELECT is_global FROM scripts WHERE script_id = $1
    `, [script_id]);
    
    if (checkResult.rows.length === 0) {
      return res.status(404).json({ error: 'Script not found' });
    }
    
    if (checkResult.rows[0].is_global) {
      return res.status(403).json({ error: 'Cannot delete global scripts' });
    }
    
    const result = await pool.query(`
      DELETE FROM scripts
      WHERE script_id = $1 AND tenant_id = $2
      RETURNING script_id
    `, [script_id, tenant_id]);
    
    if (result.rows.length === 0) {
      return res.status(404).json({ error: 'Script not found or unauthorized' });
    }
    
    res.json({ success: true, message: 'Script deleted' });
  } catch (err) {
    console.error('[Scripts] Delete error:', err);
    res.status(500).json({ error: 'Failed to delete script' });
  }
});
 
// ============================================
// SCRIPT EXECUTION
// ============================================
 
/**
 * @api {post} /scripts/execute/:agent_uuid Execute script on agent
 * @apiName ExecuteScript
 * @apiGroup Scripts
 * @apiDescription Execute a script on a connected agent via WebSocket. Provide either script_id (to fetch from library) or script_content (for ad-hoc execution). Creates an execution record and returns execution_id for tracking.
 * @apiParam {string} agent_uuid Agent UUID to execute on.
 * @apiParam {string} [script_id] Script ID from library (mutually exclusive with script_content).
 * @apiParam {string} [script_content] Ad-hoc script content (mutually exclusive with script_id).
 * @apiSuccess {boolean} success Operation success status.
 * @apiSuccess {string} execution_id Execution ID for tracking.
 * @apiSuccess {string} message Status message.
 * @apiError (Error 400) BadRequest No script content provided.
 * @apiError (Error 404) NotFound Agent not connected or script not found.
 * @apiExample {curl} Example usage:
 *     curl -X POST -H "Authorization: Bearer <token>" -H "X-Tenant-ID: <id>" -d '{"script_id":"abc123"}' https://api.example.com/scripts/execute/agent-uuid-here
 */
router.post('/execute/:agent_uuid', async (req, res) => {
  try {
    const { agent_uuid } = req.params;
    const { script_id, script_content } = req.body;
    const tenant_id = req.headers['x-tenant-id'];
    const user_id = req.user?.user_id;
    
    // Either script_id or script_content must be provided
    let scriptToRun = script_content;
    let scriptIdToLog = script_id;
    
    if (script_id && !script_content) {
      // Fetch script content from database
      const scriptResult = await pool.query(`
        SELECT script_content FROM scripts
        WHERE script_id = $1 AND (tenant_id = $2 OR is_global = true)
      `, [script_id, tenant_id]);
      
      if (scriptResult.rows.length === 0) {
        return res.status(404).json({ error: 'Script not found' });
      }
      
      scriptToRun = scriptResult.rows[0].script_content;
    }
    
    if (!scriptToRun) {
      return res.status(400).json({ error: 'No script content provided' });
    }
    
    // Check if agent is connected
    const ws = wsManager.agentConnections.get(agent_uuid);
    if (!ws || ws.readyState !== 1) {
      return res.status(404).json({ error: 'Agent not connected' });
    }
    
    // Create execution record
    const executionResult = await pool.query(`
      INSERT INTO script_executions (script_id, agent_uuid, tenant_id, executed_by, execution_status)
      VALUES ($1, $2, $3, $4, 'running')
      RETURNING execution_id
    `, [scriptIdToLog, agent_uuid, tenant_id, user_id]);
    
    const execution_id = executionResult.rows[0].execution_id;
    
    // Send script to agent via WebSocket
    ws.send(JSON.stringify({
      type: 'run_script',
      execution_id,
      payload: { script: scriptToRun }
    }));
    
    console.log(`[Scripts] Executing script on ${agent_uuid}, execution_id: ${execution_id}`);
    
    res.json({
      success: true,
      execution_id,
      message: 'Script execution started'
    });
  } catch (err) {
    console.error('[Scripts] Execute error:', err);
    res.status(500).json({ error: 'Failed to execute script' });
  }
});
 
/**
 * @api {get} /scripts/executions/:script_id Get execution history for script
 * @apiName GetScriptExecutions
 * @apiGroup Scripts
 * @apiDescription Retrieve execution history for a specific script (last 50 executions). Includes agent hostname and executor name.
 * @apiParam {string} script_id Script ID.
 * @apiSuccess {object[]} executions List of executions.
 * @apiSuccess {string} executions.execution_id Execution ID.
 * @apiSuccess {string} executions.agent_uuid Agent UUID.
 * @apiSuccess {string} executions.hostname Agent hostname.
 * @apiSuccess {string} executions.execution_status Status (running, completed, failed).
 * @apiSuccess {string} executions.stdout Script output.
 * @apiSuccess {string} executions.stderr Script errors.
 * @apiSuccess {number} executions.exit_code Exit code.
 * @apiSuccess {string} executions.executed_by_name Executor name.
 * @apiSuccess {Date} executions.started_at Execution start time.
 * @apiSuccess {Date} executions.completed_at Execution completion time.
 * @apiExample {curl} Example usage:
 *     curl -H "Authorization: Bearer <token>" -H "X-Tenant-ID: <id>" https://api.example.com/scripts/executions/abc123
 */
router.get('/executions/:script_id', async (req, res) => {
  try {
    const { script_id } = req.params;
    const tenant_id = req.headers['x-tenant-id'];
    
    const result = await pool.query(`
      SELECT 
        se.*,
        a.hostname,
        u.name as executed_by_name
      FROM script_executions se
      LEFT JOIN agents a ON se.agent_uuid = a.agent_uuid
      LEFT JOIN users u ON se.executed_by = u.user_id
      WHERE se.script_id = $1 AND se.tenant_id = $2
      ORDER BY se.started_at DESC
      LIMIT 50
    `, [script_id, tenant_id]);
    
    res.json(result.rows);
  } catch (err) {
    console.error('[Scripts] Execution history error:', err);
    res.status(500).json({ error: 'Failed to get execution history' });
  }
});
 
/**
 * @api {get} /scripts/execution/:execution_id Get execution result
 * @apiName GetExecution
 * @apiGroup Scripts
 * @apiDescription Retrieve details of a single script execution by execution ID.
 * @apiParam {string} execution_id Execution ID.
 * @apiSuccess {object} execution Execution object.
 * @apiSuccess {string} execution.execution_id Execution ID.
 * @apiSuccess {string} execution.script_id Script ID.
 * @apiSuccess {string} execution.agent_uuid Agent UUID.
 * @apiSuccess {string} execution.execution_status Status (running, completed, failed).
 * @apiSuccess {string} execution.stdout Script output.
 * @apiSuccess {string} execution.stderr Script errors.
 * @apiSuccess {number} execution.exit_code Exit code.
 * @apiSuccess {Date} execution.started_at Execution start time.
 * @apiSuccess {Date} execution.completed_at Execution completion time.
 * @apiError (Error 404) NotFound Execution not found.
 * @apiExample {curl} Example usage:
 *     curl -H "Authorization: Bearer <token>" -H "X-Tenant-ID: <id>" https://api.example.com/scripts/execution/exec-123
 */
router.get('/execution/:execution_id', async (req, res) => {
  try {
    const { execution_id } = req.params;
    const tenant_id = req.headers['x-tenant-id'];
    
    const result = await pool.query(`
      SELECT * FROM script_executions
      WHERE execution_id = $1 AND tenant_id = $2
    `, [execution_id, tenant_id]);
    
    if (result.rows.length === 0) {
      return res.status(404).json({ error: 'Execution not found' });
    }
    
    res.json(result.rows[0]);
  } catch (err) {
    console.error('[Scripts] Get execution error:', err);
    res.status(500).json({ error: 'Failed to get execution' });
  }
});
 
// ============================================
// SCRIPT MANIFEST FOR AGENT SYNC
// ============================================
 
/**
 * @api {get} /scripts/download/:script_id Download script for agent sync
 * @apiName DownloadScript
 * @apiGroup Scripts
 * @apiDescription Download script content by ID with hash and version info for agent synchronization. Used by agents to fetch new or updated scripts from the manifest.
 * @apiParam {string} script_id Script ID.
 * @apiSuccess {string} script_id Script ID.
 * @apiSuccess {string} script_name Script name.
 * @apiSuccess {string} script_content Script content.
 * @apiSuccess {string} script_language Script language.
 * @apiSuccess {string} hash SHA256 hash of script content.
 * @apiSuccess {number} version Script version.
 * @apiError (Error 404) NotFound Script not found or not accessible.
 * @apiExample {curl} Example usage:
 *     curl -H "Authorization: Bearer <token>" -H "X-Tenant-ID: <id>" https://api.example.com/scripts/download/abc123
 */
router.get('/download/:script_id', async (req, res) => {
  try {
    const { script_id } = req.params;
    const tenant_id = req.headers['x-tenant-id'];
    
    // Handle "null" string as actual NULL
    const safeTenantId = (tenant_id === 'null' || !tenant_id) ? null : tenant_id;
    
    // Get script content (must be accessible to this tenant)
    const result = await pool.query(`
      SELECT 
        s.script_id,
        s.script_name,
        s.script_content,
        s.script_language,
        sm.script_hash,
        sm.version
      FROM scripts s
      JOIN script_manifest sm ON s.script_id = sm.script_id
      WHERE s.script_id = $1 AND (s.tenant_id = $2 OR s.is_global = true)
    `, [script_id, safeTenantId]);
    
    if (result.rows.length === 0) {
      return res.status(404).json({ error: 'Script not found' });
    }
    
    const script = result.rows[0];
    
    res.json({
      script_id: script.script_id,
      script_name: script.script_name,
      script_content: script.script_content,
      script_language: script.script_language,
      hash: script.script_hash,
      version: script.version
    });
  } catch (err) {
    console.error('[Scripts] Download error:', err);
    res.status(500).json({ error: 'Failed to download script' });
  }
});
 
module.exports = router;