> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threataware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PowerShell Relay

> Connect on-premises tools to Protect without opening inbound firewall ports

## What it is

The **PowerShell Relay** is a PowerShell script that runs on a Windows server inside your network. It acts as a reverse proxy — Protect's cloud asks it to query an on-prem tool, the relay does so over your internal network, and returns the result over an outbound HTTPS connection that the relay initiated.

| Hop | From              | To                                     | Direction                                       |
| --- | ----------------- | -------------------------------------- | ----------------------------------------------- |
| 1   | ThreatAware Cloud | PowerShell Relay (your Windows server) | Relay polls cloud over outbound HTTPS 443       |
| 2   | PowerShell Relay  | On-prem tool (AD, SCCM, etc.)          | Internal network, relay-initiated               |
| 3   | PowerShell Relay  | ThreatAware Cloud                      | Returns result over the same outbound HTTPS 443 |

No inbound firewall rules. No reverse proxy infrastructure. No NAT or DMZ. The relay only makes outbound connections, exactly like a browser.

## When you need the relay

For integrations whose APIs aren't internet-accessible:

| Tool                             | Why it needs the relay                     |
| -------------------------------- | ------------------------------------------ |
| **OnPrem Active Directory**      | LDAP queries against domain controllers    |
| **SCCM / Configuration Manager** | WMI-based API on internal servers          |
| **PDQ Inventory (on-prem)**      | Local API only                             |
| **Lansweeper (on-prem)**         | If deployed on-prem rather than cloud SaaS |
| **VMware vCenter**               | Typically internal-only                    |
| Some on-prem Jamf instances      | If you run Jamf Pro on-prem                |

If your tool is cloud-hosted (Azure AD, CrowdStrike cloud, Intune, JAMF Cloud, etc.), you don't need the relay.

## Setup

<Steps>
  <Step title="Configure the integration in Protect first">
    [Settings → Integrations](/settings/integrations) → select the on-prem integration → click Connect.

    Enter:

    * **Host URL** — `https://<server>:<port>` (test in a browser first to confirm reachability)
    * **Certificate setting** — Enable bypass if your internal cert won't validate
    * **Authentication method** — Default Credentials (NTLM, for SCCM) or Manual Credentials

    Save — this generates relay files.
  </Step>

  <Step title="Pick a relay server">
    Requirements:

    * Windows Server (any supported version)
    * Network access to the target tool (LDAP, WMI, HTTPS to internal endpoint)
    * Outbound HTTPS (port 443) allowed
    * PowerShell 5.1 or higher
    * Can run a scheduled task or service

    **For the OnPrem Active Directory integration specifically**, the relay server also needs the RSAT Active Directory PowerShell module:

    ```powershell theme={null}
    Install-WindowsFeature RSAT-AD-PowerShell
    ```

    This is surfaced as the **Pre-Script Setup Command** in the Protect integration setup UI. Without it the AD relay script can't import the `ActiveDirectory` module and will error out.
  </Step>

  <Step title="Extract files to the exact path">
    The relay files (`command.cmd` + `<integration>.ps1`) must live at:

    ```text theme={null}
    C:\Scripts\ThreatAware\
    ```

    Create that folder if it doesn't exist. The scheduled task expects this path.
  </Step>

  <Step title="Test the script manually first">
    Before scheduling, run the script as a human to confirm it works.

    **If using Default Credentials (NTLM)** — for SCCM, AD:

    1. Shift + Right-click Command Prompt → **Run as different user**
    2. Enter the credentials the scheduled task will use
    3. `cd C:\Scripts\ThreatAware`
    4. `command.cmd`
    5. Watch for errors

    **If using Manual Credentials:**

    1. Open Command Prompt as Administrator
    2. `cd C:\Scripts\ThreatAware`
    3. `command.cmd`
  </Step>

  <Step title="Create a scheduled task">
    1. Open **Task Scheduler** → **Create Task** (NOT Create Basic Task)
    2. **General tab:**
       * Name: `ThreatAware PowerShell Relay - <Tool Name>`
       * **Change User or Group**: pick the service account, or `SYSTEM` for default-credential flows
       * ✓ Run whether user is logged on or not
    3. **Triggers tab:** Daily → Recur every 1 day → Repeat task every 1 hour for 1 day
    4. **Actions tab:** Start a program → Browse → `C:\Scripts\ThreatAware\command.cmd`
    5. **Settings tab:**
       * ✓ Allow task to be run on demand
       * ✓ Run task as soon as possible after a scheduled start is missed
    6. Save (prompts for password)
  </Step>

  <Step title="Verify in Protect">
    Wait 5-10 minutes after the task runs, then check [Settings → Integrations](/settings/integrations) for **CONNECTED** status.
  </Step>
</Steps>

## Frequency recommendations

| Cadence                    | When                                               |
| -------------------------- | -------------------------------------------------- |
| **Every 1 hour** (default) | Standard — matches Protect's refresh cycle         |
| **Every 2 hours**          | If the script takes > 30 minutes to run            |
| **Every 4-6 hours**        | Very large estates where AD/SCCM queries are heavy |

Set the frequency in the scheduled task's Trigger.

## Security

<CardGroup cols={3}>
  <Card title="Outbound only" icon="arrow-up-from-bracket">
    No inbound ports. The relay only initiates HTTPS 443 outbound.
  </Card>

  <Card title="Read-only credentials" icon="lock">
    Provide an account with read access to the source system. Protect can never modify.
  </Card>

  <Card title="Encrypted" icon="shield">
    All relay-to-cloud traffic uses TLS 1.2+.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Certificate error: could not establish trust">
    Internal cert isn't trusted. Either install a valid cert on the target server, OR enable **Bypass Certificate Check** in the Protect integration settings.
  </Accordion>

  <Accordion title="401 Unauthorized / Access Denied">
    * Verify credentials are correct
    * For NTLM: ensure the service account has read permissions on the source system
    * Test credentials by manually accessing the tool's web interface
  </Accordion>

  <Accordion title="Connection timeout">
    * Verify network connectivity from relay server to target
    * Confirm outbound HTTPS (443) is allowed from the relay server
    * Test the URL from the relay server's browser
  </Accordion>

  <Accordion title="Scheduled task shows but doesn't execute">
    * Enable Task History in Task Scheduler
    * Verify task is **Enabled**
    * Right-click → Run to test manually
    * Check Event Viewer for task-scheduler errors
    * Ensure the account has "Log on as a batch job" rights
  </Accordion>

  <Accordion title="Task runs but no data appears in Protect">
    * Check the script output during a manual run for silent errors
    * Verify the integration's Host URL is reachable from the relay server
    * Check [Audit Log](/settings/audit-log) for relay-side errors
  </Accordion>

  <Accordion title="Multiple relays for different tools">
    Each integration has its own pair of files. Place each in a separate folder (e.g. `C:\Scripts\ThreatAware\AD\`, `C:\Scripts\ThreatAware\SCCM\`) or run separate scheduled tasks pointing at each `command.cmd`.
  </Accordion>
</AccordionGroup>

## Multi-server / HA

For mission-critical estates, run the relay on two servers:

* Both pointed at the same integration in Protect
* Stagger the scheduled task times by 15 minutes
* Protect deduplicates the inbound data

If one relay server goes down, the other keeps the data flowing.

## See also

<CardGroup cols={3}>
  <Card title="Integrations" icon="plug" href="/integrations">
    Conceptual overview
  </Card>

  <Card title="Connection Guides" icon="book" href="/connection-guides">
    Per-tool relay setups
  </Card>

  <Card title="Troubleshooting" icon="screwdriver-wrench" href="/reference/troubleshooting">
    Wider issue index
  </Card>
</CardGroup>