docs: streamline tone across reference docs
tests / build-and-test (push) Successful in 2m7s
tests / thread-sanitizer (push) Successful in 2m35s
tests / tshark-dissector (push) Successful in 2m19s
tests / secs4j-interop (push) Successful in 36s
tests / libfuzzer (push) Successful in 3m8s

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:
2026-06-10 00:00:06 +02:00
parent d63c92166d
commit dae6bfd747
9 changed files with 130 additions and 219 deletions
+17 -23
View File
@@ -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 \