# mustafaahmed007/vps-shield architecture

> Architecture diagram of the GitHub repository mustafaahmed007/vps-shield, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mustafaahmed007/vps-shield
- Repository: https://github.com/mustafaahmed007/vps-shield

## Overview

VPS Shield is a defensive Linux VPS security toolkit organized around an operator-facing lifecycle: inspect the host, assess findings, research context, plan changes, harden with safeguards, verify, and repeat. The README documents the CLI as the orchestration layer, with separate audit, research, policy, hardening, and optional integration responsibilities. The graph preserves those documented capabilities; source excerpts were unavailable, so relationships rely on the README rather than inspected runtime calls.

Main entry points: [`scripts/shield.sh`](https://github.com/mustafaahmed007/vps-shield/blob/main/scripts/shield.sh) (Shield CLI), [`modules/research.sh`](https://github.com/mustafaahmed007/vps-shield/blob/main/modules/research.sh) (Evidence research), [`systemd/vps-shield-audit.timer`](https://github.com/mustafaahmed007/vps-shield/blob/main/systemd/vps-shield-audit.timer) (Audit schedule), [`modules/audit.sh`](https://github.com/mustafaahmed007/vps-shield/blob/main/modules/audit.sh) (Host audit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Operator workflow"]
  node_cli["Shield CLI<br/>[shield.sh]"]
  node_doctor["Environment doctor<br/>[shield.sh]"]
  node_scheduler["Audit schedule"]
  node_installer["One-click installer<br/>[install.sh]"]
end

subgraph group_assessment["Assessment and research"]
  node_audit["Host audit<br/>[audit.sh]"]
  node_scoring["Score and explain<br/>[shield.sh]"]
  node_research["Evidence research<br/>[research.sh]"]
  node_research_sources["Research providers<br/>[research.sh]"]
end

subgraph group_remediation["Policy and remediation"]
  node_policy["Security baseline<br/>[baseline.yaml]"]
  node_planning["Remediation plan<br/>[shield.sh]"]
  node_hardening["Controlled hardening<br/>[harden.sh]"]
  node_verification["Verify and monitor<br/>[harden.sh]"]
end

subgraph group_integration["Adapters and host"]
  node_integration_probes["Integration probes<br/>[integrations.sh]"]
  node_adapters["Optional adapters"]
  node_linux_host["Linux VPS"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_cli
node_operator -->|"schedules audits"| node_scheduler
node_scheduler -.->|"initiates audits"| node_cli
node_cli -->|"checks environment"| node_doctor
node_cli -->|"orchestrates audit"| node_audit
node_cli -->|"orchestrates scoring"| node_scoring
node_cli -->|"orchestrates research"| node_research
node_cli -->|"orchestrates planning"| node_planning
node_cli -->|"orchestrates hardening"| node_hardening
node_cli -->|"orchestrates verification"| node_verification
node_audit -->|"collects evidence"| node_linux_host
node_scoring -->|"evaluates baseline"| node_policy
node_research -->|"gathers evidence"| node_research_sources
node_research -.->|"uses optional providers"| node_adapters
node_planning -->|"plans against"| node_policy
node_hardening -->|"applies changes"| node_linux_host
node_verification -->|"checks state"| node_linux_host
node_cli -->|"orchestrates probes"| node_integration_probes
node_integration_probes -.->|"probes capabilities"| node_adapters
node_installer -->|"runs self-check"| node_doctor

click node_cli "https://github.com/mustafaahmed007/vps-shield/blob/main/scripts/shield.sh"
click node_doctor "https://github.com/mustafaahmed007/vps-shield/blob/main/scripts/shield.sh"
click node_scheduler "https://github.com/mustafaahmed007/vps-shield/blob/main/systemd/vps-shield-audit.timer"
click node_audit "https://github.com/mustafaahmed007/vps-shield/blob/main/modules/audit.sh"
click node_scoring "https://github.com/mustafaahmed007/vps-shield/blob/main/scripts/shield.sh"
click node_research "https://github.com/mustafaahmed007/vps-shield/blob/main/modules/research.sh"
click node_research_sources "https://github.com/mustafaahmed007/vps-shield/blob/main/modules/research.sh"
click node_policy "https://github.com/mustafaahmed007/vps-shield/blob/main/policies/baseline.yaml"
click node_planning "https://github.com/mustafaahmed007/vps-shield/blob/main/scripts/shield.sh"
click node_hardening "https://github.com/mustafaahmed007/vps-shield/blob/main/modules/harden.sh"
click node_verification "https://github.com/mustafaahmed007/vps-shield/blob/main/modules/harden.sh"
click node_integration_probes "https://github.com/mustafaahmed007/vps-shield/blob/main/modules/integrations.sh"
click node_adapters "https://github.com/mustafaahmed007/vps-shield/tree/main/integrations"
click node_installer "https://github.com/mustafaahmed007/vps-shield/blob/main/install.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_doctor,node_scheduler,node_installer toneBlue
class node_audit,node_scoring,node_research,node_research_sources toneAmber
class node_policy,node_planning,node_hardening,node_verification toneMint
class node_integration_probes,node_adapters,node_linux_host toneRose
class node_operator toneIndigo
```

## Components

### Operator workflow

- [Shield CLI](https://github.com/mustafaahmed007/vps-shield/blob/main/scripts/shield.sh): `scripts/shield.sh`
- [Environment doctor](https://github.com/mustafaahmed007/vps-shield/blob/main/scripts/shield.sh): `scripts/shield.sh`
- [Audit schedule](https://github.com/mustafaahmed007/vps-shield/blob/main/systemd/vps-shield-audit.timer): `systemd/vps-shield-audit.timer`
- [One-click installer](https://github.com/mustafaahmed007/vps-shield/blob/main/install.sh): `install.sh`

### Assessment and research

- [Host audit](https://github.com/mustafaahmed007/vps-shield/blob/main/modules/audit.sh): `modules/audit.sh`
- [Score and explain](https://github.com/mustafaahmed007/vps-shield/blob/main/scripts/shield.sh): `scripts/shield.sh`
- [Evidence research](https://github.com/mustafaahmed007/vps-shield/blob/main/modules/research.sh): `modules/research.sh`
- [Research providers](https://github.com/mustafaahmed007/vps-shield/blob/main/modules/research.sh): `modules/research.sh`

### Policy and remediation

- [Security baseline](https://github.com/mustafaahmed007/vps-shield/blob/main/policies/baseline.yaml): `policies/baseline.yaml`
- [Remediation plan](https://github.com/mustafaahmed007/vps-shield/blob/main/scripts/shield.sh): `scripts/shield.sh`
- [Controlled hardening](https://github.com/mustafaahmed007/vps-shield/blob/main/modules/harden.sh): `modules/harden.sh`
- [Verify and monitor](https://github.com/mustafaahmed007/vps-shield/blob/main/modules/harden.sh): `modules/harden.sh`

### Adapters and host

- [Integration probes](https://github.com/mustafaahmed007/vps-shield/blob/main/modules/integrations.sh): `modules/integrations.sh`
- [Optional adapters](https://github.com/mustafaahmed007/vps-shield/tree/main/integrations): `integrations`
- **Linux VPS**

### Other components

- **Operator**

## Connections

- Operator → Shield CLI: runs commands (evidence: `README.md`)
- Operator → Audit schedule: schedules audits (evidence: `README.md`)
- Audit schedule → Shield CLI: initiates audits (evidence: `README.md`)
- Shield CLI → Environment doctor: checks environment (evidence: `README.md`)
- Shield CLI → Host audit: orchestrates audit (evidence: `README.md`)
- Shield CLI → Score and explain: orchestrates scoring (evidence: `README.md`)
- Shield CLI → Evidence research: orchestrates research (evidence: `README.md`)
- Shield CLI → Remediation plan: orchestrates planning (evidence: `README.md`)
- Shield CLI → Controlled hardening: orchestrates hardening (evidence: `README.md`)
- Shield CLI → Verify and monitor: orchestrates verification (evidence: `README.md`)
- Host audit → Linux VPS: collects evidence (evidence: `README.md`)
- Score and explain → Security baseline: evaluates baseline (evidence: `README.md`)
- Evidence research → Research providers: gathers evidence (evidence: `README.md`)
- Evidence research → Optional adapters: uses optional providers (evidence: `README.md`)
- Remediation plan → Security baseline: plans against (evidence: `README.md`)
- Controlled hardening → Linux VPS: applies changes (evidence: `README.md`)
- Verify and monitor → Linux VPS: checks state (evidence: `README.md`)
- Shield CLI → Integration probes: orchestrates probes (evidence: `README.md`)
- Integration probes → Optional adapters: probes capabilities (evidence: `README.md`)
- One-click installer → Environment doctor: runs self-check (evidence: `README.md`)
