@phigon/observer 8.0.1

package/scripts/managed-service.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// Produces reviewable deployment files. It never modifies services or firewalls
+// on the developer's machine. Run the generated installer through company MDM.
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, posix, resolve, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function serviceFiles(config) {
+  const { platform, node, observer, dataDirectory, controlPlane, grpc, serviceUser = "phigon" } = config;
+  if (!["windows", "linux", "darwin"].includes(platform)) throw new Error("Unsupported managed platform.");
+  const absolute = platform === "windows" ? (value) => /^[A-Za-z]:[\\/]/u.test(value) : posix.isAbsolute;
+  for (const path of [node, observer, dataDirectory]) {
+    if (typeof path !== "string" || !absolute(path) || /[\u0000\r\n%]/u.test(path)) throw new Error("Managed deployment requires absolute paths without control characters or expansion markers.");
+    if (platform === "windows" && /[<>"|?*']/u.test(path)) throw new Error("Windows deployment paths contain unsupported characters.");
+  }
+  const targetPaths = platform === "windows" ? win32 : posix;
+  if (targetPaths.normalize(dataDirectory) === targetPaths.parse(dataDirectory).root) throw new Error("Guardian data requires its own directory, never a filesystem root.");
+  for (const endpoint of [controlPlane, grpc]) {
+    if (typeof endpoint !== "string" || /[\u0000\r\n]/u.test(endpoint)) throw new Error("Invalid managed endpoint.");
+    const url = new URL(endpoint);
+    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) throw new Error("Managed endpoints require HTTPS without embedded credentials.");
+  }
+  if (!/^[a-z_][a-z0-9_-]{0,31}$/u.test(serviceUser)) throw new Error("Invalid service account.");
+  const ps = (value) => "'" + value.replaceAll("'", "''") + "'";
+  if (platform === "windows") {
+    return { "install-guardian.ps1": `# Run as administrator through your company's device management.
+$ErrorActionPreference = 'Stop'
+$taskNode = ${ps(node)}
+$taskObserver = ${ps(observer)}
+$taskData = ${ps(dataDirectory)}
+$identity = [Security.Principal.WindowsIdentity]::GetCurrent()
+if (-not ([Security.Principal.WindowsPrincipal]$identity).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) { throw 'Administrator deployment is required.' }
+if (-not (Test-Path -LiteralPath $taskNode -PathType Leaf) -or -not (Test-Path -LiteralPath $taskObserver -PathType Leaf)) { throw 'Install and verify the release before registering Guardian.' }
+$taskAncestor = [IO.Path]::GetFullPath($taskData)
+while ($taskAncestor) {
+  if ((Test-Path -LiteralPath $taskAncestor) -and ((Get-Item -LiteralPath $taskAncestor -Force).Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'Guardian data path must not traverse reparse points.' }
+  $taskAncestor = Split-Path -Path $taskAncestor -Parent
+}
+[IO.Directory]::CreateDirectory($taskData) | Out-Null
+& "$env:SystemRoot\\System32\\icacls.exe" $taskData /inheritance:r /grant:r '*S-1-5-18:(OI)(CI)F' '*S-1-5-32-544:(OI)(CI)F' | Out-Null
+if ($LASTEXITCODE -ne 0) { throw 'Guardian data ACL could not be secured.' }
+# Existing explicit grants are not removed by icacls /grant:r. Reject an
+# insecure enrollment directory instead of starting with exposed credentials.
+$taskPaths = @((Get-Item -LiteralPath $taskData -Force)) + @(Get-ChildItem -LiteralPath $taskData -Force -Recurse)
+foreach ($taskPath in $taskPaths) {
+  if ($taskPath.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw 'Guardian data must not contain reparse points.' }
+  $taskAcl = Get-Acl -LiteralPath $taskPath.FullName
+  foreach ($taskRule in $taskAcl.GetAccessRules($true, $true, [Security.Principal.SecurityIdentifier])) {
+    if ($taskRule.AccessControlType -eq [Security.AccessControl.AccessControlType]::Allow -and $taskRule.IdentityReference.Value -notin @('S-1-5-18', 'S-1-5-32-544')) { throw 'Remove non-administrator data access before starting Guardian.' }
+  }
+  if ($taskAcl.GetOwner([Security.Principal.SecurityIdentifier]).Value -notin @('S-1-5-18', 'S-1-5-32-544')) { throw 'Guardian data ownership must belong to SYSTEM or Administrators.' }
+}
+# A SYSTEM startup task supervises process review. Per-user collection paths and
+# machine pairing must be provisioned separately into the protected data path.
+$taskArguments = '"' + $taskObserver + '" run'
+$taskAction = New-ScheduledTaskAction -Execute $taskNode -Argument $taskArguments
+$taskTrigger = New-ScheduledTaskTrigger -AtStartup
+$taskSettings = New-ScheduledTaskSettingsSet -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) -ExecutionTimeLimit ([TimeSpan]::Zero) -StartWhenAvailable -MultipleInstances IgnoreNew
+$taskPrincipal = New-ScheduledTaskPrincipal -UserId 'SYSTEM' -LogonType ServiceAccount -RunLevel Highest
+# Environment file is used by Node, rather than machine-wide environment changes.
+$taskEnv = Join-Path $taskData 'service.env'
+@'
+PHIGON_DATA_DIR='${dataDirectory}'
+PHIGON_CONTROL_PLANE_URL=${controlPlane}
+PHIGON_GRPC_URL=${grpc}
+'@ | Set-Content -LiteralPath $taskEnv -Encoding utf8
+$taskAction = New-ScheduledTaskAction -Execute $taskNode -Argument ('--env-file="' + $taskEnv + '" ' + $taskArguments)
+Register-ScheduledTask -TaskName 'PhigonGuardian' -Action $taskAction -Trigger $taskTrigger -Settings $taskSettings -Principal $taskPrincipal -Force | Out-Null
+Start-ScheduledTask -TaskName 'PhigonGuardian'
+` };
+  }
+  const xml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+  if (platform === "darwin") return { "com.phigon.guardian.plist": `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>com.phigon.guardian</string>
+<key>ProgramArguments</key><array><string>${xml(node)}</string><string>${xml(observer)}</string><string>run</string></array>
+<key>UserName</key><string>${xml(serviceUser)}</string>
+<key>EnvironmentVariables</key><dict><key>PHIGON_DATA_DIR</key><string>${xml(dataDirectory)}</string><key>PHIGON_CONTROL_PLANE_URL</key><string>${xml(controlPlane)}</string><key>PHIGON_GRPC_URL</key><string>${xml(grpc)}</string></dict>
+<key>RunAtLoad</key><true/><key>KeepAlive</key><true/><key>ThrottleInterval</key><integer>10</integer>
+<key>ProcessType</key><string>Background</string><key>Umask</key><integer>63</integer>
+</dict></plist>
+` };
+  const unit = (value) => '"' + value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%") + '"';
+  const executableArgument = (value) => unit(value.replaceAll("$", "$$"));
+  return { "phigon-guardian.service": `[Unit]
+Description=Phigon Guardian enterprise observer
+After=network-online.target
+Wants=network-online.target
+StartLimitIntervalSec=0
+
+[Service]
+Type=simple
+User=${serviceUser}
+Group=${serviceUser}
+ExecStart=${executableArgument(node)} ${executableArgument(observer)} run
+Environment=${unit("PHIGON_DATA_DIR=" + dataDirectory)}
+Environment=${unit("PHIGON_CONTROL_PLANE_URL=" + controlPlane)}
+Environment=${unit("PHIGON_GRPC_URL=" + grpc)}
+Restart=always
+RestartSec=5
+UMask=0077
+NoNewPrivileges=yes
+AmbientCapabilities=CAP_KILL CAP_DAC_READ_SEARCH
+CapabilityBoundingSet=CAP_KILL CAP_DAC_READ_SEARCH
+ProtectSystem=strict
+ProtectKernelTunables=yes
+ProtectKernelModules=yes
+ProtectControlGroups=yes
+RestrictSUIDSGID=yes
+LockPersonality=yes
+ReadWritePaths=${unit(dataDirectory)}
+KillMode=control-group
+TimeoutStopSec=15
+
+[Install]
+WantedBy=multi-user.target
+` };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [configPath, output] = process.argv.slice(2);
+  if (!configPath || !output) throw new Error("Usage: node managed-service.mjs <deployment.json> <output-directory>");
+  const files = serviceFiles(JSON.parse(await readFile(configPath, "utf8")));
+  const directory = resolve(output); await mkdir(directory, { recursive: true, mode: 0o700 });
+  for (const [name, content] of Object.entries(files)) {
+    const destination = join(directory, name);
+    try { await access(destination); throw new Error(`Deployment file already exists: ${name}`); } catch (error) { if (error.code !== "ENOENT") throw error; }
+    await writeFile(destination, content, { flag: "wx", mode: 0o600 });
+    process.stdout.write(`${destination}\n`);
+  }
+}

package/scripts/verify-guardian-release.mjs

@@ -0,0 +1,42 @@
+import { lstat, readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+
+export function verifyNativeHeader(bytes, platform, architecture) {
+  if (bytes.length < 256) throw new Error("Guardian executable is incomplete.");
+  const arm = architecture === "arm64";
+  if (platform === "windows") {
+    const pe = bytes.readUInt32LE(0x3c);
+    if (bytes.toString("ascii", 0, 2) !== "MZ" || pe > bytes.length - 6 || bytes.readUInt32LE(pe) !== 0x4550 || bytes.readUInt16LE(pe + 4) !== (arm ? 0xaa64 : 0x8664)) {
+      throw new Error("Guardian Windows executable has the wrong format or architecture.");
+    }
+  } else if (platform === "linux") {
+    if (!bytes.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])) || bytes[4] !== 2 || bytes[5] !== 1 || bytes.readUInt16LE(18) !== (arm ? 183 : 62)) {
+      throw new Error("Guardian Linux executable has the wrong format or architecture.");
+    }
+  } else if (platform === "darwin") {
+    if (bytes.readUInt32LE(0) !== 0xfeedfacf || bytes.readUInt32LE(4) !== (arm ? 0x100000c : 0x1000007)) {
+      throw new Error("Guardian macOS executable has the wrong format or architecture.");
+    }
+  } else throw new Error("Unknown Guardian platform.");
+}
+
+export async function verifyGuardianRelease() {
+  for (const platform of ["windows", "linux", "darwin"]) {
+    for (const architecture of ["amd64", "arm64"]) {
+      const name = `guardian-runner-${platform}-${architecture}${platform === "windows" ? ".exe" : ""}`;
+      const file = new URL(`../dist/bin/${name}`, import.meta.url);
+      const stat = await lstat(file);
+      if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`Release requires a regular native executable: ${name}`);
+      verifyNativeHeader(await readFile(file), platform, architecture);
+      if (platform !== "windows" && (stat.mode & 0o111) !== 0o111) {
+        throw new Error(`${name} lacks Unix executable permissions. Build and pack the portable release on Linux or macOS using the release workflow.`);
+      }
+    }
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await verifyGuardianRelease();
+  process.stdout.write("Guardian release verified: six native executables with correct architectures and permissions.\n");
+}

package/scripts/windows-app-control.mjs

@@ -0,0 +1,117 @@
+// Generates a reviewable AppLocker deployment package. Rendering never changes
+// the current machine's policy, services, registry, or firewall.
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function applicationControlFiles(config) {
+  if (!config || !["audit", "enforce"].includes(config.mode) || !/^S-1-\d+(?:-\d+)+$/u.test(config.user_or_group_sid ?? "") ||
+      !Array.isArray(config.applications) || config.applications.length < 1 || config.applications.length > 64) throw new Error("Application control requires an explicit mode, account/group SID and 1–64 applications.");
+  const seen = new Set();
+  for (const app of config.applications) {
+    if (!app || typeof app.path !== "string" || !/^[A-Za-z]:[\\/].+\.exe$/iu.test(app.path) || /[\u0000-\u001f<>"|?*%\[\]]/u.test(app.path) || /(?:^|[\\/])\.{1,2}(?:[\\/]|$)/u.test(app.path) ||
+        !["hash", "publisher"].includes(app.rule_type) || seen.has(app.path.toLowerCase())) throw new Error("Applications require unique absolute .exe paths and hash/publisher rule types.");
+    seen.add(app.path.toLowerCase());
+  }
+  const settings = JSON.stringify({ mode: config.mode, user_or_group_sid: config.user_or_group_sid, applications: config.applications }, null, 2);
+  return {
+    "applications.json": settings + "\n",
+    "Build-GuardianAppControl.ps1": `# Windows PowerShell with the AppLocker module. Generates files only.
+$ErrorActionPreference = 'Stop'
+Import-Module AppLocker -ErrorAction Stop
+$configuration = Get-Content -LiteralPath (Join-Path $PSScriptRoot 'applications.json') -Raw | ConvertFrom-Json
+$previousPath = Join-Path $PSScriptRoot 'previous-policy.xml'
+$policyPath = Join-Path $PSScriptRoot 'guardian-policy.xml'
+if ((Test-Path -LiteralPath $previousPath) -or (Test-Path -LiteralPath $policyPath)) { throw 'Use a fresh deployment directory; existing review artifacts will not be overwritten.' }
+$previous = Get-AppLockerPolicy -Local -Xml
+[xml]$policy = $previous
+$mode = if ($configuration.mode -eq 'enforce') { 'Enabled' } else { 'AuditOnly' }
+$collection = $policy.SelectSingleNode('/AppLockerPolicy/RuleCollection[@Type="Exe"]')
+if (-not $collection) {
+  $collection = $policy.CreateElement('RuleCollection')
+  $collection.SetAttribute('Type','Exe')
+  $policy.DocumentElement.AppendChild($collection) | Out-Null
+}
+$existingRules = @($collection.SelectNodes('FilePathRule|FileHashRule|FilePublisherRule'))
+if ($existingRules.Count -gt 0 -and $collection.EnforcementMode -ne $mode) { throw 'Existing EXE rules use another enforcement mode. Review that policy through company device management before combining it.' }
+$collection.SetAttribute('EnforcementMode',$mode)
+if ($existingRules.Count -eq 0) {
+  # A deny-only deployment must not accidentally become a machine allowlist.
+  $allow = $policy.CreateElement('FilePathRule')
+  $allow.SetAttribute('Id',[guid]::NewGuid().ToString()); $allow.SetAttribute('Name','Preserve other application access')
+  $allow.SetAttribute('Description','Initial default for an otherwise empty EXE collection')
+  $allow.SetAttribute('UserOrGroupSid','S-1-1-0'); $allow.SetAttribute('Action','Allow')
+  $conditions = $policy.CreateElement('Conditions'); $path = $policy.CreateElement('FilePathCondition'); $path.SetAttribute('Path','*')
+  $conditions.AppendChild($path) | Out-Null; $allow.AppendChild($conditions) | Out-Null; $collection.AppendChild($allow) | Out-Null
+}
+foreach ($app in $configuration.applications) {
+  if (-not (Test-Path -LiteralPath $app.path -PathType Leaf)) { throw 'A selected application is missing from this reference machine.' }
+  $information = Get-AppLockerFileInformation -Path $app.path
+  [xml]$generated = New-AppLockerPolicy -FileInformation $information -RuleType $app.rule_type -User $configuration.user_or_group_sid -Xml
+  $rules = @($generated.SelectNodes('/AppLockerPolicy/RuleCollection[@Type="Exe"]/FileHashRule|/AppLockerPolicy/RuleCollection[@Type="Exe"]/FilePublisherRule'))
+  if ($rules.Count -eq 0) { throw 'No specific application rule could be generated. Publisher rules require signed application identity.' }
+  foreach ($rule in $rules) {
+    if (($app.rule_type -eq 'hash' -and $rule.LocalName -ne 'FileHashRule') -or ($app.rule_type -eq 'publisher' -and $rule.LocalName -ne 'FilePublisherRule')) { throw 'Generated application identity does not match the requested rule type.' }
+    if ($app.rule_type -eq 'publisher') {
+      $identity = $rule.Conditions.FilePublisherCondition
+      if (-not $identity) { throw 'Publisher identity is missing.' }
+      foreach ($part in @($identity.PublisherName, $identity.ProductName, $identity.BinaryName)) {
+        if ([string]::IsNullOrWhiteSpace($part) -or $part.Contains('*') -or $part.Contains('?')) { throw 'Publisher identity must identify one application, not an entire software publisher.' }
+      }
+      $identity.BinaryVersionRange.SetAttribute('LowSection','0.0.0.0'); $identity.BinaryVersionRange.SetAttribute('HighSection','*')
+    }
+    $rule.SetAttribute('Action','Deny'); $rule.SetAttribute('Name','Phigon Guardian: application prohibited')
+    $collection.AppendChild($policy.ImportNode($rule,$true)) | Out-Null
+  }
+}
+$previous | Set-Content -LiteralPath $previousPath -Encoding UTF8
+$policy.Save($policyPath)
+Write-Output 'Review guardian-policy.xml and previous-policy.xml before deploying. No OS policy has been applied.'
+`,
+    "Apply-GuardianAppControl.ps1": `# Deploy the reviewed package as administrator using company device management.
+$ErrorActionPreference = 'Stop'
+Import-Module AppLocker -ErrorAction Stop
+$identity = [Security.Principal.WindowsIdentity]::GetCurrent()
+if (-not ([Security.Principal.WindowsPrincipal]$identity).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) { throw 'Administrator deployment is required.' }
+[xml]$expected = Get-Content -LiteralPath (Join-Path $PSScriptRoot 'previous-policy.xml') -Raw
+[xml]$current = Get-AppLockerPolicy -Local -Xml
+if ($current.OuterXml -ne $expected.OuterXml) { throw 'Local policy changed after review. Rebuild against the current policy; no changes applied.' }
+Set-Service -Name AppIDSvc -StartupType Automatic
+Start-Service -Name AppIDSvc
+Set-AppLockerPolicy -XmlPolicy (Join-Path $PSScriptRoot 'guardian-policy.xml')
+& (Join-Path $PSScriptRoot 'Verify-GuardianAppControl.ps1')
+`,
+    "Verify-GuardianAppControl.ps1": `param([string]$UserSid)
+$ErrorActionPreference = 'Stop'
+Import-Module AppLocker -ErrorAction Stop
+$configuration = Get-Content -LiteralPath (Join-Path $PSScriptRoot 'applications.json') -Raw | ConvertFrom-Json
+if ([string]::IsNullOrWhiteSpace($UserSid)) { $UserSid = $configuration.user_or_group_sid }
+if ($UserSid -notmatch '^S-1-\\d+(-\\d+)+$') { throw 'Verification requires an account SID.' }
+$effective = Get-AppLockerPolicy -Effective
+[xml]$xml = Get-AppLockerPolicy -Effective -Xml
+$collection = $xml.SelectSingleNode('/AppLockerPolicy/RuleCollection[@Type="Exe"]')
+$decisions = @($effective | Test-AppLockerPolicy -Path @($configuration.applications | ForEach-Object { $_.path }) -User $UserSid)
+$denied = @($decisions | Where-Object { $_.PolicyDecision -eq 'Denied' -or $_.PolicyDecision -eq 'DeniedByDefault' })
+$verified = $collection.EnforcementMode -eq 'Enabled' -and (Get-Service -Name AppIDSvc).Status -eq 'Running' -and $denied.Count -eq $configuration.applications.Count
+@{ evidence='effective_os_policy'; policy_verified=$verified; tested_identity=$UserSid; mode=$collection.EnforcementMode; checked_applications=$decisions.Count; runtime_test_required=$true } | ConvertTo-Json
+if ($configuration.mode -eq 'enforce' -and -not $verified) { throw 'Effective enforcement does not match this deployment. Check domain/MDM policy and OS support.' }
+`,
+    "Rollback-GuardianAppControl.ps1": `$ErrorActionPreference = 'Stop'
+Import-Module AppLocker -ErrorAction Stop
+[xml]$deployed = Get-Content -LiteralPath (Join-Path $PSScriptRoot 'guardian-policy.xml') -Raw
+[xml]$current = Get-AppLockerPolicy -Local -Xml
+if ($current.OuterXml -ne $deployed.OuterXml) { throw 'Local policy changed after deployment. Automatic rollback would overwrite other administrator changes.' }
+Set-AppLockerPolicy -XmlPolicy (Join-Path $PSScriptRoot 'previous-policy.xml')
+Write-Output 'Previous local application policy restored. Application Identity service remains available for other company policies.'
+`,
+  };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [configPath, output] = process.argv.slice(2);
+  if (!configPath || !output) throw new Error("Usage: node windows-app-control.mjs <applications.json> <output-directory>");
+  const files = applicationControlFiles(JSON.parse(await readFile(configPath, "utf8")));
+  const directory = resolve(output); await mkdir(directory, { recursive: true, mode: 0o700 });
+  for (const [name, content] of Object.entries(files)) await writeFile(join(directory, name), content, { flag: "wx", mode: 0o600 });
+  process.stdout.write(`Generated ${Object.keys(files).length} application-control artifacts in ${directory}.\n`);
+}