The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
# How the Windows package scripts run beacon.exe. Dot-sourced by install-endpoint.ps1 and
# uninstall-endpoint.ps1, so the two cannot drift apart on it.
#
# An MSI custom action has no console and no time limit of its own. A beacon.exe call that never
# returns therefore holds the whole installation open: msiexec waits on the action, a fleet tool
# (Intune, Workspace ONE, SCCM) waits on msiexec, and nothing records which step it was. So every
# call made here is bounded, and every call leaves a record.
#
# The record is a file of its own in the temporary directory of the account running the script --
# SYSTEM, for the MSI -- because nothing else survives: Windows Installer keeps no output from an
# executable custom action, and an uninstall removes the payload directory. The file name is new for
# each run and the file is created rather than opened, so a file an ordinary user planted under that
# name in advance can never receive SYSTEM's writes. The log is diagnostics only: if it cannot be
# created, the script carries on without it.
# ERROR_TIMEOUT. Returned by Invoke-BeaconBounded for a call it had to stop, so a caller can tell
# "beacon.exe failed" from "beacon.exe never finished".
$script:BeaconTimeoutExitCode = 1460
# Returned by Invoke-BeaconBounded when beacon.exe could not be started at all (missing, locked,
# blocked by application control, access denied). No process ran, so there is no exit code of its
# own to report, and this is not a timeout.
$script:BeaconLaunchFailedExitCode = -1
$script:BeaconPackageLog = $null
$script:BeaconPackageLogPath = $null
function Open-BeaconPackageLog {
param([string]$Action)
$name = 'beacon-package-{0}-{1:yyyyMMddTHHmmss}-{2}.log' -f $Action, (Get-Date), ([Guid]::NewGuid().ToString('N').Substring(0, 8))
$path = Join-Path ([System.IO.Path]::GetTempPath()) $name
try {
$stream = New-Object System.IO.FileStream($path, [System.IO.FileMode]::CreateNew, [System.IO.FileAccess]::Write, [System.IO.FileShare]::Read)
$writer = New-Object System.IO.StreamWriter($stream, (New-Object System.Text.UTF8Encoding($false)))
$writer.AutoFlush = $true
$script:BeaconPackageLog = $writer
$script:BeaconPackageLogPath = $path
} catch {
$script:BeaconPackageLog = $null
$script:BeaconPackageLogPath = $null
}
}
# Written to the console as well as the log, through [Console] rather than Write-Output: Write-Output
# inside a function becomes part of that function's return value, which would corrupt the exit code
# Invoke-BeaconBounded returns.
function Write-BeaconPackageLog {
param([string]$Message)
$line = '{0:o} {1}' -f (Get-Date), $Message
[Console]::Out.WriteLine($line)
if ($null -ne $script:BeaconPackageLog) {
try { $script:BeaconPackageLog.WriteLine($line) } catch { $script:BeaconPackageLog = $null }
}
}
function Close-BeaconPackageLog {
if ($null -ne $script:BeaconPackageLog) {
try { $script:BeaconPackageLog.Dispose() } catch { }
$script:BeaconPackageLog = $null
}
}
# Quotes one argument for the command line a Windows program parses back into argv, which is how
# Go's runtime reads it. Windows PowerShell 5.1 runs on .NET Framework, whose ProcessStartInfo takes
# one command-line string rather than an argument list, and the paths passed here contain spaces
# (C:\Program Files\...). Backslashes are literal except in a run that ends at a quote, where each
# one has to be doubled -- which includes a run at the very end, followed by the closing quote.
function ConvertTo-BeaconArgument {
param([string]$Value)
if ($Value.Length -gt 0 -and $Value -notmatch '[\s"]') { return $Value }
$escaped = [regex]::Replace($Value, '(\\*)"', { param($m) $m.Groups[1].Value + $m.Groups[1].Value + '\"' })
$escaped = [regex]::Replace($escaped, '(\\+)$', { param($m) $m.Groups[1].Value + $m.Groups[1].Value })
return '"' + $escaped + '"'
}
function Write-BeaconStream {
param([string]$Name, $Task)
# The pipes close once every process holding them has exited, which the stop below guarantees
# for beacon's own process tree. A reader is still bounded, because a process outside that tree
# could have inherited one.
try {
if (-not $Task.Wait(5000)) {
Write-BeaconPackageLog " ($Name did not close)"
return
}
$text = $Task.Result
} catch {
Write-BeaconPackageLog " ($Name could not be read: $($_.Exception.Message))"
return
}
foreach ($line in ($text -split "`r?`n")) {
if ($line.Length -gt 0) { Write-BeaconPackageLog " $Name> $line" }
}
}
# Runs beacon.exe with Arguments, waits at most TimeoutSeconds, and returns its exit code,
# $BeaconTimeoutExitCode once it had to be stopped, or $BeaconLaunchFailedExitCode when it could not
# be started. Output is recorded line by line in the package log.
#
# A beacon.exe still running fifteen seconds before the bound writes every goroutine's stack to
# stderr (BEACON_DEBUG_STACKS_AFTER), so a call that hangs names the code it is stuck in, not just
# the command.
function Invoke-BeaconBounded {
param([string]$Beacon, [string[]]$Arguments, [int]$TimeoutSeconds)
# Windows PowerShell turns a native command's stderr into a terminating error under the callers'
# 'Stop' preference once it is redirected, and taskkill reports a child that already exited on
# stderr. Stopping a hung call must never be what fails the install or uninstall.
$ErrorActionPreference = 'Continue'
$display = 'beacon ' + ($Arguments -join ' ')
Write-BeaconPackageLog "running: $display (bound ${TimeoutSeconds}s)"
$info = New-Object System.Diagnostics.ProcessStartInfo
$info.FileName = $Beacon
$info.Arguments = (@($Arguments | ForEach-Object { ConvertTo-BeaconArgument $_ })) -join ' '
$info.UseShellExecute = $false
$info.CreateNoWindow = $true
$info.RedirectStandardOutput = $true
$info.RedirectStandardError = $true
$info.StandardOutputEncoding = [System.Text.Encoding]::UTF8
$info.StandardErrorEncoding = [System.Text.Encoding]::UTF8
$info.EnvironmentVariables['BEACON_DEBUG_STACKS_AFTER'] = "$([Math]::Max(1, $TimeoutSeconds - 15))s"
# Caught here because the 'Continue' preference above would otherwise let a failed start carry on
# with no process, and be reported as a timeout.
try {
$process = [System.Diagnostics.Process]::Start($info)
} catch {
Write-BeaconPackageLog "could not start ${display}: $($_.Exception.Message)"
return $script:BeaconLaunchFailedExitCode
}
# Both streams are drained concurrently. Reading one to the end before the other deadlocks as
# soon as beacon fills the pipe nobody is reading.
$stdout = $process.StandardOutput.ReadToEndAsync()
$stderr = $process.StandardError.ReadToEndAsync()
$exited = $process.WaitForExit($TimeoutSeconds * 1000)
if (-not $exited) {
Write-BeaconPackageLog "TIMEOUT: $display did not finish within ${TimeoutSeconds}s; stopping it and its child processes"
& taskkill.exe /T /F /PID $process.Id 2>&1 | ForEach-Object { Write-BeaconPackageLog " $_" }
$global:LASTEXITCODE = 0
$null = $process.WaitForExit(10000)
}
Write-BeaconStream 'stdout' $stdout
Write-BeaconStream 'stderr' $stderr
if (-not $exited) { return $script:BeaconTimeoutExitCode }
Write-BeaconPackageLog "exit $($process.ExitCode): $display"
return $process.ExitCode
}