VSI GLOBAL // ENTERPRISE ARCHITECTURE

Protective Intelligence Stream

5 min read

Protective Intelligence Stream

Deliverable SYS-008. Structure per cc02-standards/SYSTEM-STANDARD.md. Every component traces to a design basis (NEED/REQ) and to an acceptance criterion.

1. Purpose and Design Basis

1.1 Scope and Objective

The Protective Intelligence Stream (v2) is a region-configured threat alerting engine that ingests real-time feeds to identify and disseminate violent incidents, transport disruptions, and emergency hazards relevant to a principal’s Area of Operations (AO).

1.2 Design Basis

This system replaces the legacy vsi-feed-1 architecture with a structured matching model. It enforces a clean separation of concerns by placing all LLM-based analysis off the hot path, ensuring deterministic and low-latency alert delivery.

1.3 Needs

  • NEED-SYS-008-01: The protective detail requires real-time alerting of violent and emergency incidents within the AO to execute immediate principal evacuation or route changes.
    • Source: Team Leader (RF)
    • Context: Manual monitoring of feeds introduces delays up to three hours, which increases risk to the principal.
  • NEED-SYS-008-02: The system administration requires a secure deployment footprint.
    • Source: Systems Engineer (CS)
    • Context: Avoids credential exposure or host takeover via group-chat-driven LLM features.

1.4 Requirements

  • REQ-SYS-008-01 (Traceability: NEED-SYS-008-01): When a raw feed item is received, the Threat Alert Stream processor shall parse the payload for matching threat and place terms within 500 milliseconds [VR-SYS-008-01].
    • Verification Method: Test (T)
  • REQ-SYS-008-02 (Traceability: NEED-SYS-008-01): When threat and place terms match, the Threat Alert Stream processor shall compute Likelihood and Impact scores mapping to the 1-25 scale within 100 milliseconds [VR-SYS-008-02].
    • Verification Method: Analysis (A)
  • REQ-SYS-008-03 (Traceability: NEED-SYS-008-01): When a composite risk score of 11 or higher is calculated, the Threat Alert Stream processor shall publish an alert message containing a BLUF header to the ART-threat-alert-stream destination within 1 second [VR-SYS-008-03].
    • Verification Method: Test (T)
  • REQ-SYS-008-04 (Traceability: NEED-SYS-008-01): When feed polling fails for 3 consecutive attempts, the Threat Alert Stream processor shall raise a priority system alert to the administration console within 10 seconds [VR-SYS-008-04].
    • Verification Method: Demonstration (D)
  • REQ-SYS-008-05 (Traceability: NEED-SYS-008-02): Under runtime operating conditions, the Threat Alert Stream daemon shall run under a dedicated non-root user account with read-only access to its configuration file [VR-SYS-008-05].
    • Verification Method: Inspection (I)

2. Architecture As Built

+------------------------------------------------------------------------+
| SYS-008 Protective Intelligence Stream (Hot Path)                      |
|                                                                        |
|  Feeds ---> Ingestion ---> Term Matcher ---> Score Engine ---> Publish  |
|                               ^ (Gazetteer)                       |    |
+-------------------------------------------------------------------|----+
                                                                    v
                                                            ART-threat-alert-stream
                                                                    |
                                                                    v
                                                     +--------------+--------------+
                                                     |                             |
                                                     v                             v
                                            EP-016 Daily Brief             AGT-001 Agentic
                                            (Operational Detail)           Pipeline (D-05)

2.1 Enrichment Tier Boundary (SYS-008 / AGT-001)

To ensure system latency remains low and deterministic, a strict boundary is established:

  • SYS-008 Ownership (D-03 Systems Infrastructure): Owns ingestion, term parsing, L x I severity scoring, and alert publishing. It is strictly local, runs no LLMs or natural language generation, and processes matches in sub-second times.
  • AGT-001 Ownership (D-05 Agentic Operations): Consumes the alert stream asynchronously. It owns summarizing, clustering, pattern analysis, and generating the daily brief using LLMs. It sits off the critical path and does not block real-time alert delivery.

3. Components and Bill of Materials

ComponentSpecVendor / LinkPriceTierStatus
Ingestion DaemonPython 3.12 service with feedparser and requestsInternal$0.00-SELECTED
Gazetteer DatabaseJSON-formatted geography matrix (AO specific)Internal$0.00-SELECTED
Token Matcher EngineRegular expression string parsing engineInternal$0.00-SELECTED

4. Build and Deployment

4.1 Ingestion Sources

  • Public News RSS Feeds:
    • Endpoint 1: <placeholder-rss-endpoint-1>
    • Endpoint 2: <placeholder-rss-endpoint-2>
  • Curated Social Media Accounts:
    • Endpoint 1: <placeholder-social-endpoint-1>
    • Endpoint 2: <placeholder-social-endpoint-2>
  • Emergency Dispatch Transcripts:
    • Endpoint 1: <placeholder-dispatch-endpoint-1>

4.2 Systemd Configuration

Deploy the service using a systemd service unit template configured to restart automatically on failure. Configure variables inside the /etc/default/prot-intel configuration file.

5. Hardening Baseline

  • Run the daemon under a dedicated, unprivileged system user sc-alerter.
  • Restrict configuration file permissions to read-only for the service owner (chmod 0400).
  • Sandbox the systemd daemon using ProtectSystem=strict and PrivateTmp=true parameters to isolate the host filesystem.

6. Integration Points

  • Inputs: SYS-006 (Telegram Platform integration for command receipt).
  • Requires: ART-region-package (Provides regional threat lexicon and AO geography).
  • Provides: ART-threat-alert-stream (Structured JSON incident feed to consumers EP-016 and AGT-001).

7. Acceptance Tests

CriterionMethodExpected ResultReference
REQ-SYS-008-01TestParse feed payload and identify matching terms within 500 millisecondsVR-SYS-008-01
REQ-SYS-008-02AnalysisCalculate Likelihood and Impact matching the cc02 matrix within 100 millisecondsVR-SYS-008-02
REQ-SYS-008-03TestPublish JSON alert payload to ART-threat-alert-stream within 1 second of scoringVR-SYS-008-03
REQ-SYS-008-04DemonstrationGenerate priority administrative alert when three consecutive polling cycles failVR-SYS-008-04
REQ-SYS-008-05InspectionConfirm service process runs under non-root account and config permissions are restrictedVR-SYS-008-05

8. Run and Maintenance Handover

  • Service Control: Manage via systemctl restart prot-intel@<region>.
  • Logging: Access logs via journalctl -u prot-intel@<region> -n 100.
  • Ownership: Systems Engineer (CS).

Annex A: Severity Matrix Mapping

The Likelihood (1-5) and Impact (1-5) values are calculated using term weights and geographic tiers:

  • Likelihood (1-5): Determined by the geographic proximity tier of the matched place term:
    • client_venue ⇒ 5
    • mobility_hub ⇒ 4
    • district ⇒ 3
    • city ⇒ 2
    • outside ⇒ 1
  • Impact (1-5): Determined by the severity weight of the matched threat term:
    • High (Explosion, active shooter, weapons discharge) ⇒ 5
    • Medium (Protests, vehicle collisions, fire) ⇒ 3
    • Low (General delays, weather advisories) ⇒ 1

Composite Risk Score = Likelihood x Impact (1-25):

  • Critical (21-25): Instant page alert (notifying).
  • High (16-20): Instant page alert (notifying).
  • Elevated (11-15): Instant page alert (notifying).
  • Moderate (6-10): Ambient informational signal (non-notifying).
  • Low (1-5): Ambient informational signal (non-notifying).

Annex B: Delivery Schema Contract

Alert JSON schema format sent to ART-threat-alert-stream:

{
  "incident_id": "INC-YYYYMMDD-###",
  "timestamp": "ISO-8601-TIMESTAMP",
  "threat_term": "string",
  "place_term": "string",
  "place_tier": "client_venue|mobility_hub|district|city",
  "likelihood": 1..5,
  "impact": 1..5,
  "score": 1..25,
  "severity": "Low|Moderate|Elevated|High|Critical",
  "bluf_summary": "string",
  "raw_source": "string"
}

END OF SYSTEM

Model wiring

Generated from cell frontmatter at publish time.

Graph View

Backlinks