docs: streamline tone across reference docs
Tone pass across the non-tutorial markdown — README, PROOFS,
ARCHITECTURE, BENCHMARKS, COMPLIANCE, FAQ, MES_INTEROP, SECURITY,
and interop/README. Three patterns came out:
- Bug-history war stories ("Past interop sweeps surfaced…",
"What these harnesses caught: 1. Strict U-width parsing…").
- Chat-with-reader framing ("Don't skip TLS unless…", "Treat as a
punch list", "If you're running in a pod…", "Misconfiguration
incidents drop dramatically").
- Self-referential narration ("we ship", "our codec", "the
codebase's most-tested layer", "three orders of magnitude above
fab load", "the gift that keeps giving").
README also drops the standalone ThreadSanitizer subsection under
Build details (now a single line under the new Testing section).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
+17
-23
@@ -1,16 +1,14 @@
|
||||
# Security operations guide
|
||||
|
||||
HSMS is the spec's wire protocol: plain TCP, no auth, no encryption.
|
||||
That's what every fab tool ships and what every MES expects, and we
|
||||
don't change it. Security comes from the network layer around the
|
||||
HSMS socket. This doc has the concrete configs you'll need; no
|
||||
hand-waving.
|
||||
HSMS is plain TCP — no auth, no encryption. That's what every fab
|
||||
tool ships and what every MES expects. Security comes from the
|
||||
network layer around the HSMS socket; this doc has the concrete
|
||||
configs.
|
||||
|
||||
> If you're shipping to a production fab, treat every section here
|
||||
> as mandatory unless your fab security architect signs off on a
|
||||
> deviation in writing. HSMS on an exposed network with no controls
|
||||
> is how an unauthenticated MES impersonation incident becomes a
|
||||
> wafer-loss event.
|
||||
For production deployments treat the sections below as mandatory
|
||||
unless your fab security architect signs off on a deviation. HSMS
|
||||
on an exposed network with no controls is how MES impersonation
|
||||
becomes a wafer-loss incident.
|
||||
|
||||
## 1. Network isolation
|
||||
|
||||
@@ -66,7 +64,7 @@ nft list set inet filter mes_hosts # confirm the set is loaded
|
||||
|
||||
### 1.3 Pod-network policy (Kubernetes / K3s deployments)
|
||||
|
||||
If you're running the equipment in a pod, use a `NetworkPolicy`:
|
||||
For pod deployments, use a `NetworkPolicy`:
|
||||
|
||||
```yaml
|
||||
apiVersion: networking.k8s.io/v1
|
||||
@@ -144,9 +142,7 @@ secs_server --port 5000 --bind 127.0.0.1 \
|
||||
--config /etc/acme-secsgem/equipment.yaml ...
|
||||
```
|
||||
|
||||
(The `--bind` flag is a small addition you'll need to add to
|
||||
`apps/secs_server.cpp` if you adopt this pattern — the demo binary
|
||||
binds INADDR_ANY today. Filed as a follow-up.)
|
||||
The demo binary binds INADDR_ANY; a `--bind` flag is a follow-up.
|
||||
|
||||
### 2.2 stunnel.conf — MES side (initiator)
|
||||
|
||||
@@ -171,10 +167,9 @@ sslVersionMin = TLSv1.3
|
||||
### 2.3 Performance impact
|
||||
|
||||
TLS adds ~50 µs per round-trip on modern hardware (measured via
|
||||
`secs_bench` with stunnel in the loop vs. direct connection). At a
|
||||
few hundred S6F11 events/sec sustained that's invisible. Don't skip
|
||||
TLS for performance reasons unless your latency budget is genuinely
|
||||
sub-millisecond.
|
||||
`secs_bench` with stunnel in the loop vs. direct connection). At
|
||||
sustained rates in the few-hundred-events/sec range, the overhead
|
||||
is invisible against the fab-tool latency budget.
|
||||
|
||||
## 3. Authentication
|
||||
|
||||
@@ -243,14 +238,13 @@ ExecStartPre=/usr/local/libexec/secsgem-verify-configs.sh
|
||||
ExecStart=/usr/local/bin/secs_server --config /etc/acme-secsgem/equipment.yaml ...
|
||||
```
|
||||
|
||||
If any signature fails, the unit refuses to start. Misconfiguration
|
||||
incidents drop dramatically when this is in place.
|
||||
If any signature fails, the unit refuses to start.
|
||||
|
||||
### 4.2 Validate before signing
|
||||
|
||||
Always run `secs_server --validate-config` against the YAML before
|
||||
signing it. Signing a broken config just transmits the breakage
|
||||
cryptographically:
|
||||
`secs_server --validate-config` must run clean against the YAML
|
||||
before signing — signing a broken config only transmits the
|
||||
breakage cryptographically:
|
||||
|
||||
```sh
|
||||
secs_server --validate-config \
|
||||
|
||||
Reference in New Issue
Block a user