aboutsummaryrefslogtreecommitdiffstats
path: root/docs/architectuur.md
blob: fd35b34192e66b265881998f394d56c73749deb8 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
# Architectuur

## Overzicht

```
beheermachine                         server (niets extra geïnstalleerd)
─────────────                         ──────────────────────────────────
Trace-module                          sshd
  │  serverlijst (YAML)                 │  Subsystem powershell → pwsh -sshs
  │                                     ▼
  └─ SSH-remoting ──────────────────► pwsh-sessie van Trace
     (één sessie per server)            │  Get-PSHostProcessInfo / Get-Process
                                        │  NamedPipeConnectionInfo(pid)
                                        ▼
                                      pwsh-proces van het script
                                        └─ runspace 1 → Debugger
```

Alle logica zit in de module op de beheermachine. Op een server zijn alleen
`pwsh` (7.4 of hoger) en het `powershell`-subsystem van sshd nodig.

## Debugging van licht tot diep

| Niveau | Hoe | Grijpt in? |
|---|---|---|
| 0: logs | De parser zoekt in het script waar het naartoe logt (`Start-Transcript`, `Out-File`, `Add-Content`); die bestanden worden via SSH opgehaald | Nee |
| 1: wrapper | Het script start via een wrapper met `$ErrorActionPreference = 'Break'` | Alleen bij een fout |
| 2: tracepoints | Breakpoint met een actie zonder `break`: legt een waarde vast, het script loopt door | Licht |
| 3: attach | Aanhaken aan een al draaiend `pwsh`-proces en daar niveau 1 en 2 toepassen | Ja |

Niveau 1 tot 3 mogen alleen op servers met `trace_debug: true`.

## Attachen aan een draaiend script (niveau 3)

Aangetoond in `poc/attach`. De keten:

1. **SSH-remoting** naar de server: `New-PSSession -HostName … -KeyFilePath …`.
2. **Het script vinden**: `pwsh`-processen waarvan de opdrachtregel naar het script wijst.
3. **Attachen**: `[NamedPipeConnectionInfo]::new($pid)` en `[runspacefactory]::CreateRunspace(...)`.
   Die runspace draait *in* het doelproces. Het is dezelfde weg die `Enter-PSHostProcess` gebruikt,
   maar dan zonder interactieve prompt. Op Linux is de pipe een Unix-socket in `/tmp`.
4. **De runspace van het script**: `Get-Runspace -Id 1`.
5. **Breakpoints met acties** rechtstreeks op `$runspace.Debugger`.

### Bevindingen uit de PoC

- `Set-PSBreakpoint -Runspace` weigert in een geattachte runspace:
  `Breakpoints cannot be set in the remote session because remote debugging is not supported by the current host.`
  De debugger-API rechtstreeks werkt wel: `SetVariableBreakpoint`, `SetLineBreakpoint`, `RemoveBreakpoint`.
- Acties moeten losse scriptblocks zijn (`[scriptblock]::Create(...)`), anders draaien ze in de
  verkeerde runspace. Hun resultaten gaan via een gedeelde wachtrij in het doelproces terug.
- Een actie zonder `break` stopt het script niet. Na het loskoppelen loopt het script gewoon door.
- Attachen vraagt dezelfde gebruiker als het script, of root: de socket is van die gebruiker.
- Bij het loskoppelen logt het doelproces een onschuldige `TransportError`.

### Nog niet aangetoond

- Echt stoppen, rondkijken en hervatten (`DebuggerStop`-event, `Debug-Runspace`).
- Een crashrapport bij een fout in een al draaiend script.

## Uitvoer

| Wat | Formaat | Waar |
|---|---|---|
| Crashrapport | JSON, één bestand per crash | Beheermachine, één map per server |
| Tracepoint-records | JSON Lines, één record per regel | Beheermachine, één bestand per sessie |

Het wegschrijven zit in één functie, zodat een ander formaat (bijvoorbeeld binair) één functie vervangt.