[Feat] Add security recommendations for node and service operators

Aperta
#41 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
52/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Ambito
documentation

Direzione di ricerca

Add own-node/security.md, then list it in .vitepress/config.mts and link it from own-node/installation.md and own-node/configuration.md. First read those pages and the cited node files, including AGENTS.md, to ground the ADAMANT-specific guidance. Verify every command on Ubuntu 24.04 and 26.04, then run npm run docs:build; done means the recommendation page follows the writing rules and builds successfully.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

documentation Guideline Nodes Security

Summary

Add a page to the node documentation with security recommendations for people who run ADAMANT nodes and related services: a generic, depersonalized version of the VPS practices that contributors collected while operating infrastructure (see Adamant-im/adamant#279).

Motivation

ADAMANT is a decentralized open-source project with no company and no central team: nodes and services are run by independent operators, and each operator decides how to run and protect them. The docs cover installation and configuration in own-node/, but not how to keep a host that runs a node patched, exposed only where needed, and recoverable.

Several pitfalls are specific to ADAMANT and are missing from generic hardening checklists:

  • A reverse proxy or a Tor onion service in front of the node makes every request appear to come from 127.0.0.1, which the node's loopback API and forging whitelists then admit
  • Forced termination (kill -9, PM2's default 1600 ms kill_timeout, systemd's default 90-second stop timeout) can leave mem_* tables inconsistent and trigger a long rebuild
  • A PostgreSQL restart, for example during an automatic package update, can leave a running node stalled until it is restarted (Adamant-im/adamant#280)
  • PostgreSQL from the PGDG repository, which tools/install_node.sh uses, is not covered by Ubuntu's default automatic security updates
  • Coin-node RPC frontends used by wallets expose every daemon method that the frontend does not filter, so a public node must not hold a wallet

Detailed description

The page is a memo of recommendations, not a requirement or an official policy. It should open with a clear statement:

  • These are recommendations collected by independent contributors; there is no ADAMANT team, company, or support service behind them
  • Every operator chooses their own approaches and tools and is solely responsible for the security of the nodes and services they run
  • Following the recommendations does not guarantee security; operators must adapt every example to their own environment and verify it

Suggested scope, as short checklist-style sections:

  • Access: key-only SSH with a separate key per person and device, no password logins, provider console and recovery access; an optional non-default SSH port and optional port knocking, with their limits stated (they reduce noise, they are not access control)
  • Firewall: one firewall owner on the host, IPv4 and IPv6 covered, the node's P2P/API port public, databases and control interfaces private; container-published ports bypass a simple host input policy
  • Updates: automatic security updates, coordinated database updates with a graceful node stop, third-party repositories that need their own update routine, regular vulnerability checks of the OS and the Node.js runtime
  • Node exposure: api.access.public, the API and forging whitelists, trustProxy, reverse proxies and onion services, the WebSocket port
  • Process lifecycle: one catchable termination signal and waiting for Cleaned up successfully, PM2 kill_timeout, systemd stop timeouts and ordering against PostgreSQL, recovery after crashes and reboots, encrypted signers that start locked
  • Monitoring: height compared with peers, disk space and inodes, certificate expiry checked on the public URL, backup freshness
  • Secrets and backups: passphrases kept out of shell history, logs, and shared machines; encrypted off-host backups; tested restores that never start a second active signer
  • If something goes wrong: restrict access, preserve logs, rebuild from a clean image, rotate credentials, move funds with a clean device

Writing rules for the page:

  • No real IP addresses, hostnames, ports, knock sequences, or onion addresses; use the documentation ranges 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32, and example.com
  • No team or organization voice such as "we", "our servers", or "the ADAMANT team"; write for an independent operator
  • No absolute claims such as "secure" or "unhackable"; describe trade-offs and limits instead
  • Tool-neutral: name tools such as nftables, knockd, Zabbix, or Trivy as examples, not as requirements
  • Verify every command on Ubuntu 24.04 and 26.04 before publishing, and cite node repository files for node behavior (config.default.json, tools/install_node.sh, the graceful shutdown rules in AGENTS.md)
  • Link known issues instead of describing unreleased behavior as available

Alternatives

  • Link only generic external hardening guides. They miss the ADAMANT-specific pitfalls listed above.
  • Keep the guidance with the contributors who wrote it. Independent operators would keep rediscovering the same failures.

Proposed technical implementation

  • Add own-node/security.md ("Security recommendations") and list it in .vitepress/config.mts after the installation and configuration pages
  • Link it from own-node/installation.md and own-node/configuration.md
  • Prepare the text as a depersonalized excerpt of the contributors' operator guide and review it against the writing rules above
  • Validate with npm run docs:build

Notes

  • Related: Adamant-im/adamant#279 (VPS security guide), Adamant-im/adamant#280 (node stalls after a PostgreSQL restart), Adamant-im/adamant#282 (install and repair scripts review)
  • The docs AGENTS.md terminology section says "Use ADM for the token", while community wording elsewhere calls ADM a coin; consider aligning it in the same change
Lingua principale
CSS
Stelle
119
Fork
2
Metriche di merge delle PR
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Adamant-im/docs

Tutte le issue di Adamant-im/docs

Issue simili

Altre issue su Documentation

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.