Skip to main content
Shield is designed with a distributed-first architecture. While it integrates deeply with the Dotset Cloud for centralized management and analytics, it is built to ensure that your CI/CD pipelines and local runs are never blocked by external factors like network issues or server maintenance.

​
Design Philosophy

The core protection engine runs entirely on your infrastructure. Cloud connectivity is used for:
  1. Centralized Policy Sync: Fetching your custom security patterns and allowlists.
  2. Security Analytics: Reporting protection events (detections, redactions) to your dashboard.
If the cloud is unreachable, Shield enters a resilient-operational state where it prioritizes protection and pipeline stability over real-time reporting.

​
Fail-Safe Policy Management

Shield uses an aggressive caching strategy to ensure you always have a valid security posture available.

​
Immediate Sync

When you first run dotset link, Shield immediately fetches your latest security policies and stores them in an encrypted local cache (.dotset/policies.json).

​
Background Refresh

During every run or ci command, Shield checks the age of the local cache.
  • Under 1 Hour: Uses the cached policies for maximum speed.
  • Over 1 Hour: Attempts a background refresh from the cloud.

​
Automatic Fallback

If a refresh fails due to a network or server issue, Shield automatically falls back to the last known-good cached policy. This ensures that your detection logic remains active even when you are completely offline.

​
Telemetry Buffering

Losing security data during an outage is a risk handled by our built-in buffering system.
  • Offline Buffering: If a protection event cannot be reported to the dashboard, it is saved locally to .dotset/pending_telemetry.json.
  • Automatic Retry: The CLI stores up to 50 pending events and automatically attempts to re-upload them at the start of any subsequent Shield command.
  • Consistency: Once connectivity is restored, all buffered events flow into your dashboard, ensuring your security audits remains complete.

​
Operational Visibility

Shield keeps you informed of your connection status via terminal indicators:
IndicatorMeaning
`☁️ cloudpolicies synced`Connected and up-to-date with cloud policies.
`☁️ cloudpolicies synced (offline)`Server unreachable; using the most recent cached policies.
`⚠ linkedoffline`Project is linked but no local policies were found; falling back to default patterns.

​
FAQ

No. Shield is designed to never break a build due to network or server issues. It will log a warning but proceed with the best available protection (cached or default).
Yes. The local policy cache is stored in your project directory and is only accessible to users with access to that environment.