Initial OfficeCom Sentinel client and deployment assets
This commit is contained in:
OfficeCom Codex
523
docs/attacktracer-ninja-v2-repo-plan.md
Normal file
523
docs/attacktracer-ninja-v2-repo-plan.md
Normal file
@@ -0,0 +1,523 @@
|
||||
# AttackTracer Ninja V2 Repo Plan
|
||||
|
||||
## Purpose
|
||||
|
||||
This document turns the V2 architecture into a concrete repository refactor plan.
|
||||
|
||||
It answers:
|
||||
|
||||
- which existing components should be removed or deprecated
|
||||
- which new components should be created
|
||||
- how the client package should be structured
|
||||
- what the n8n webhook contract should look like
|
||||
- in which order the migration should happen
|
||||
|
||||
## Target result
|
||||
|
||||
The repository should end up centered around one endpoint client package that:
|
||||
|
||||
- runs on every managed Windows device
|
||||
- writes NinjaOne device fields locally
|
||||
- uploads signed JSON reports to n8n
|
||||
- can be installed and updated from NinjaOne using GitLab-hosted release artifacts
|
||||
|
||||
The repository should no longer rely on:
|
||||
|
||||
- share mirroring
|
||||
- a central `AttackTracerNinjaServer`
|
||||
- organization aggregation on a Windows endpoint
|
||||
|
||||
## Existing components to remove or deprecate
|
||||
|
||||
## Remove from active architecture
|
||||
|
||||
These should be retired from the primary product path:
|
||||
|
||||
- `scripts/build-attacktracer-org-report.ps1`
|
||||
- `installer/runtime-build-attacktracer-org-report.ps1`
|
||||
- `scripts/run-attacktracer-ninja-server.ps1`
|
||||
- `installer/runtime-run-attacktracer-ninja-server.ps1`
|
||||
- `scripts/build-attacktracer-server-installer.ps1`
|
||||
- `installer/server-install-attacktracer-ninja-server.ps1`
|
||||
- `installer/server-uninstall-attacktracer-ninja-server.ps1`
|
||||
- `installer/AttackTracerNinjaServerBootstrapper/*`
|
||||
- `docs/attacktracer-ninja-server.md`
|
||||
- share-based org-report playbook content in `docs/ninjaone-org-report-playbook.md`
|
||||
|
||||
## Keep only as legacy reference
|
||||
|
||||
These can remain temporarily during migration but should be clearly marked legacy:
|
||||
|
||||
- `scripts/run-attacktracer-ninja-monitor.ps1`
|
||||
- `scripts/run-attacktracer-ninja.ps1`
|
||||
- `docs/ninjaone-monitoring-playbook.md`
|
||||
- `config/attacktracer-settings.example.json`
|
||||
|
||||
## Existing components to preserve and refactor
|
||||
|
||||
These are still valuable and should become the base for V2:
|
||||
|
||||
- `src/AttackTracerNinjaCli/AttackScanner.cs`
|
||||
- `src/AttackTracerNinjaCli/VulnerabilityCorrelation.cs`
|
||||
- `src/AttackTracerNinjaCli/Models.cs`
|
||||
- `src/AttackTracerNinjaCli/JsonOptions.cs`
|
||||
- `src/AttackTracerNinjaCli/Program.cs`
|
||||
- `src/AttackTracerNinjaCli/ScanOptions.cs`
|
||||
|
||||
Core scanning logic should remain in C#.
|
||||
|
||||
## New repository structure
|
||||
|
||||
Recommended target layout:
|
||||
|
||||
```text
|
||||
src/
|
||||
AttackTracerNinjaCli/
|
||||
AttackTracerNinjaCli.csproj
|
||||
Commands/
|
||||
ScanCommand.cs
|
||||
UploadCommand.cs
|
||||
ScanAndUploadCommand.cs
|
||||
VersionCommand.cs
|
||||
Security/
|
||||
HmacSigner.cs
|
||||
NonceStore.cs
|
||||
ProtectedSecretStore.cs
|
||||
Transport/
|
||||
N8nUploadClient.cs
|
||||
UploadEnvelopeBuilder.cs
|
||||
Models/
|
||||
ReportEnvelope.cs
|
||||
ScanReport.cs
|
||||
UploadResult.cs
|
||||
Configuration/
|
||||
ClientConfiguration.cs
|
||||
ConfigurationLoader.cs
|
||||
|
||||
scripts/
|
||||
install-attacktracer-ninja.ps1
|
||||
uninstall-attacktracer-ninja.ps1
|
||||
update-attacktracer-ninja.ps1
|
||||
run-attacktracer-ninja.ps1
|
||||
publish-ninja-fields.ps1
|
||||
|
||||
config/
|
||||
attacktracer-client.example.json
|
||||
update-channel.example.json
|
||||
|
||||
docs/
|
||||
attacktracer-ninja-v2-architecture.md
|
||||
attacktracer-ninja-v2-repo-plan.md
|
||||
attacktracer-ninja-v2-n8n-contract.md
|
||||
attacktracer-ninja-v2-deployment.md
|
||||
|
||||
build/
|
||||
build-client-package.ps1
|
||||
build-release-manifest.ps1
|
||||
|
||||
samples/
|
||||
webhook-payload.example.json
|
||||
version.example.json
|
||||
```
|
||||
|
||||
## New endpoint client responsibilities
|
||||
|
||||
## Binary responsibilities
|
||||
|
||||
The compiled client should do these jobs:
|
||||
|
||||
- local attack scanning
|
||||
- vulnerability correlation
|
||||
- JSON report generation
|
||||
- report signing
|
||||
- authenticated upload to n8n
|
||||
- stable exit codes
|
||||
- machine-readable output for NinjaOne wrappers
|
||||
|
||||
## Wrapper responsibilities
|
||||
|
||||
PowerShell wrappers should only do:
|
||||
|
||||
- install/uninstall
|
||||
- update
|
||||
- local config bootstrap
|
||||
- invoking the binary
|
||||
- publishing NinjaOne device custom fields
|
||||
- logging wrapper-level failures
|
||||
|
||||
## New client command model
|
||||
|
||||
Recommended commands:
|
||||
|
||||
### `scan`
|
||||
|
||||
Performs local scan and writes a report file.
|
||||
|
||||
Example:
|
||||
|
||||
```powershell
|
||||
AttackTracerNinjaCli.exe scan --output "C:\ProgramData\AttackTracerNinja\reports\latest.json" --ninja-output
|
||||
```
|
||||
|
||||
### `upload`
|
||||
|
||||
Uploads an existing report to n8n.
|
||||
|
||||
Example:
|
||||
|
||||
```powershell
|
||||
AttackTracerNinjaCli.exe upload --report "C:\ProgramData\AttackTracerNinja\reports\latest.json"
|
||||
```
|
||||
|
||||
### `scan-and-upload`
|
||||
|
||||
Performs a scan and directly uploads the result.
|
||||
|
||||
Example:
|
||||
|
||||
```powershell
|
||||
AttackTracerNinjaCli.exe scan-and-upload --output "C:\ProgramData\AttackTracerNinja\reports\latest.json" --ninja-output
|
||||
```
|
||||
|
||||
### `version`
|
||||
|
||||
Prints installed version and build metadata.
|
||||
|
||||
## Config model
|
||||
|
||||
Recommended local config file:
|
||||
|
||||
- `C:\ProgramData\AttackTracerNinja\config\attacktracer-client.json`
|
||||
|
||||
Recommended fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": "2.0",
|
||||
"environment": "production",
|
||||
"lookbackDays": 7,
|
||||
"topFindings": 10,
|
||||
"n8nWebhookUrl": "https://n8n.example.com/webhook/attacktracer-ingest",
|
||||
"deviceIdentifierMode": "machineName",
|
||||
"uploadTimeoutSeconds": 30,
|
||||
"enableVulnerabilityCorrelation": true,
|
||||
"vulnerabilityCsvPath": "",
|
||||
"secretReference": "device-default"
|
||||
}
|
||||
```
|
||||
|
||||
Secrets should not be stored here in clear text.
|
||||
|
||||
## Local secret handling plan
|
||||
|
||||
## Secret storage
|
||||
|
||||
Create a protected local secret file under:
|
||||
|
||||
- `C:\ProgramData\AttackTracerNinja\secrets\upload-secret.dat`
|
||||
|
||||
Use DPAPI machine protection to encrypt the secret.
|
||||
|
||||
## Secret bootstrap
|
||||
|
||||
Initial rollout options:
|
||||
|
||||
1. NinjaOne install task writes a tenant token once and immediately protects it with DPAPI.
|
||||
2. Later evolution: unique per-device secret issued centrally.
|
||||
|
||||
Recommended first cut:
|
||||
|
||||
- tenant-level ingest secret wrapped with DPAPI
|
||||
- HMAC signature over request metadata + payload hash
|
||||
|
||||
## n8n webhook contract
|
||||
|
||||
## Endpoint request
|
||||
|
||||
Method:
|
||||
|
||||
- `POST`
|
||||
|
||||
URL:
|
||||
|
||||
- provided via config, for example:
|
||||
- `https://n8n.example.com/webhook/attacktracer-ingest`
|
||||
|
||||
Headers:
|
||||
|
||||
- `Content-Type: application/json`
|
||||
- `X-ATN-Device`
|
||||
- `X-ATN-Timestamp`
|
||||
- `X-ATN-Nonce`
|
||||
- `X-ATN-Version`
|
||||
- `X-ATN-Payload-SHA256`
|
||||
- `X-ATN-Signature`
|
||||
|
||||
Body:
|
||||
|
||||
- JSON scan report only
|
||||
|
||||
Signature input recommendation:
|
||||
|
||||
```text
|
||||
device + "\n" + timestamp + "\n" + nonce + "\n" + version + "\n" + payloadSha256
|
||||
```
|
||||
|
||||
Algorithm:
|
||||
|
||||
- `HMAC-SHA256`
|
||||
|
||||
## n8n validation rules
|
||||
|
||||
n8n should reject when:
|
||||
|
||||
- any required header is missing
|
||||
- timestamp is outside tolerance
|
||||
- nonce already exists
|
||||
- payload hash mismatches body
|
||||
- signature mismatches
|
||||
- schema is invalid
|
||||
|
||||
## Suggested report payload schema
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": "2.0",
|
||||
"machineName": "WSUS",
|
||||
"generatedAtUtc": "2026-07-16T19:12:00Z",
|
||||
"clientVersion": "2.0.0",
|
||||
"baseStatus": "ok",
|
||||
"alertState": "ok",
|
||||
"totalEvents": 0,
|
||||
"uniqueIpCount": 0,
|
||||
"errorCount": 0,
|
||||
"attackFindings": [],
|
||||
"vulnerabilityCorrelation": {
|
||||
"totalCount": 0,
|
||||
"criticalCount": 0,
|
||||
"highCvssCount": 0
|
||||
},
|
||||
"runtime": {
|
||||
"startedAtUtc": "2026-07-16T19:11:57Z",
|
||||
"finishedAtUtc": "2026-07-16T19:12:00Z",
|
||||
"uploadAttempted": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## GitLab release plan
|
||||
|
||||
## Release artifacts
|
||||
|
||||
Each release should publish:
|
||||
|
||||
- `AttackTracerNinjaClient-win-x64.zip`
|
||||
- `AttackTracerNinjaClient-win-x64.zip.sha256`
|
||||
- `version.json`
|
||||
|
||||
## ZIP layout
|
||||
|
||||
```text
|
||||
AttackTracerNinjaClient-win-x64.zip
|
||||
app/
|
||||
AttackTracerNinjaCli.exe
|
||||
AttackTracerNinjaCli.dll
|
||||
scripts/
|
||||
install-attacktracer-ninja.ps1
|
||||
uninstall-attacktracer-ninja.ps1
|
||||
update-attacktracer-ninja.ps1
|
||||
run-attacktracer-ninja.ps1
|
||||
publish-ninja-fields.ps1
|
||||
config/
|
||||
attacktracer-client.example.json
|
||||
VERSION.txt
|
||||
```
|
||||
|
||||
## Manifest format
|
||||
|
||||
```json
|
||||
{
|
||||
"channel": "stable",
|
||||
"version": "2.0.0",
|
||||
"artifactUrl": "https://gitlab.example.com/group/project/-/releases/v2.0.0/downloads/AttackTracerNinjaClient-win-x64.zip",
|
||||
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
||||
"publishedAtUtc": "2026-07-16T19:15:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## NinjaOne task model
|
||||
|
||||
## Task A: install/update client
|
||||
|
||||
Runs as SYSTEM.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- fetch `version.json`
|
||||
- compare with local version
|
||||
- download artifact when newer
|
||||
- verify SHA-256
|
||||
- verify Authenticode signature on executable
|
||||
- install or update package
|
||||
|
||||
## Task B: run scan
|
||||
|
||||
Runs as SYSTEM on each endpoint.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- invoke `run-attacktracer-ninja.ps1`
|
||||
- publish device custom fields
|
||||
- trigger upload to n8n
|
||||
|
||||
## Device custom field path
|
||||
|
||||
Keep the current device-level field strategy.
|
||||
|
||||
Wrappers should continue using:
|
||||
|
||||
- `Ninja-Property-Set` when available
|
||||
- Ninja CLI fallback if needed
|
||||
|
||||
Fields to preserve:
|
||||
|
||||
- `attacktracerstatus`
|
||||
- `attacktracerreason`
|
||||
- `attacktracerbasestatus`
|
||||
- `attacktracerevents`
|
||||
- `attacktraceruniqueips`
|
||||
- `attacktracercvecritical`
|
||||
- `attacktracercvetotal`
|
||||
- `attacktracermode`
|
||||
- `attacktracertriggered`
|
||||
- `attacktracerlastscanutc`
|
||||
|
||||
## Concrete code refactor plan
|
||||
|
||||
## Step 1: isolate scan model
|
||||
|
||||
Refactor current CLI so scan output is represented by one stable report class.
|
||||
|
||||
Create:
|
||||
|
||||
- `Models/ScanReport.cs`
|
||||
|
||||
Move report shape ownership there.
|
||||
|
||||
## Step 2: add transport layer
|
||||
|
||||
Create:
|
||||
|
||||
- `Transport/N8nUploadClient.cs`
|
||||
- `Transport/UploadEnvelopeBuilder.cs`
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- prepare headers
|
||||
- hash payload
|
||||
- sign request
|
||||
- upload with timeout and retry policy
|
||||
|
||||
## Step 3: add secret protection
|
||||
|
||||
Create:
|
||||
|
||||
- `Security/ProtectedSecretStore.cs`
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- store secret using DPAPI
|
||||
- load secret at runtime
|
||||
|
||||
## Step 4: add nonce/replay support
|
||||
|
||||
Create:
|
||||
|
||||
- `Security/NonceStore.cs`
|
||||
|
||||
Local nonce history is optional, but useful for diagnostics.
|
||||
|
||||
## Step 5: split commands
|
||||
|
||||
Refactor `Program.cs` into command-oriented classes:
|
||||
|
||||
- `ScanCommand.cs`
|
||||
- `UploadCommand.cs`
|
||||
- `ScanAndUploadCommand.cs`
|
||||
- `VersionCommand.cs`
|
||||
|
||||
## Step 6: simplify wrappers
|
||||
|
||||
Replace older server/share assumptions in wrappers.
|
||||
|
||||
`run-attacktracer-ninja.ps1` should become:
|
||||
|
||||
- invoke binary
|
||||
- capture output
|
||||
- write Ninja device fields
|
||||
- exit with monitoring-friendly code
|
||||
|
||||
## Step 7: replace build pipeline
|
||||
|
||||
Create:
|
||||
|
||||
- `build/build-client-package.ps1`
|
||||
- `build/build-release-manifest.ps1`
|
||||
|
||||
Deprecate:
|
||||
|
||||
- heavy installer-first flow if ZIP distribution is enough
|
||||
|
||||
## Step 8: deprecate server package
|
||||
|
||||
Mark these as legacy and remove from active release build:
|
||||
|
||||
- `AttackTracerNinjaServer*`
|
||||
- org HTML writer logic
|
||||
- share mirroring flow
|
||||
|
||||
## Implementation order
|
||||
|
||||
## Phase A: repo cleanup and design freeze
|
||||
|
||||
1. Mark server/share docs as legacy
|
||||
2. Add new config and payload docs
|
||||
3. Freeze V2 JSON schema
|
||||
|
||||
## Phase B: client refactor
|
||||
|
||||
1. Add command split
|
||||
2. Add signed upload path
|
||||
3. Add DPAPI secret handling
|
||||
4. Keep existing scan logic intact
|
||||
|
||||
## Phase C: packaging
|
||||
|
||||
1. Build ZIP package
|
||||
2. Build version manifest
|
||||
3. Add install/update scripts
|
||||
|
||||
## Phase D: central integration
|
||||
|
||||
1. Build n8n ingest workflow
|
||||
2. Build Postgres schema
|
||||
3. Build NinjaOne org-field update workflow
|
||||
|
||||
## Phase E: rollout
|
||||
|
||||
1. Pilot group
|
||||
2. Validate cadence and missing-report detection
|
||||
3. Roll out widely
|
||||
4. Retire server/share path
|
||||
|
||||
## Final recommendation
|
||||
|
||||
Implement V2 as:
|
||||
|
||||
- compiled endpoint collector
|
||||
- PowerShell operational wrapper
|
||||
- GitLab-hosted signed releases
|
||||
- NinjaOne-based deployment and update
|
||||
- n8n-based central ingestion and org aggregation
|
||||
|
||||
This gives a cleaner codebase and a safer operational model than extending the old share/server architecture further.
|
||||
Reference in New Issue
Block a user