User guide

For people who have Loomscope running and want answers out of it. If you are installing or operating it, read the DevOps guide instead.

Contents

• The mental model
• First run
• Discovery
• Hosts and services
• Topology
• Vulnerabilities
• Certificates
• History and change tracking
• Sites
• Cloud inventory
• Custom service signatures
• The AI assistant
• Roles and permissions

---

The mental model

Four concepts explain most of the interface.

A network is a CIDR you have told Loomscope about. Nothing is scanned until a network exists — Loomscope never probes anything you have not declared.

A daemon is the process that does the scanning. It lives on the network it scans and polls the control plane for work, so it needs no inbound connectivity. One deployment can have many.

A host is a discovered machine, identified by a stable fingerprint rather than by IP, so it survives DHCP changes. Hosts accumulate services, ports, interfaces, addresses and certificates.

A site is a grouping — a building, a datacentre, a client. Daemons, hosts and networks belong to a site, and the site picker in the header filters everything you see.

A useful way to hold it: networks say where to look, daemons do the looking, hosts are what was found, sites decide what you are currently looking at.

First run

1. Sign in with the administrator account created during installation.
2. Check a daemon is connected — the daemon list shows online with a recent heartbeat. If it does not, no scanning will happen; see the DevOps guide.
3. Add a network under Networks → Add network. Use the CIDR you want scanned, IPv4 or IPv6. Start with one small range.
4. Wait about 30 seconds. A /24 completes a cold scan in under 30 seconds on a normal network.
5. Open Hosts. Results appear as they arrive; the page updates live.

If nothing appears after a couple of minutes, the two usual causes are a daemon that cannot reach the range, and a firewall dropping the probes.

Discovery

The Discovery page shows scan sessions — queued, running, finished or stalled — with the daemon that ran each one and its target.

Running a scan on demand. Pick a network and a daemon, then Enqueue scan. The scheduler also runs scans automatically; an ad-hoc run does not disturb that.

How a host is found. Loomscope sweeps with ICMP, ARP on local segments, and TCP connect probes on common ports, in both address families. A host that answers nothing at all will not be discovered by active scanning — that is what SNMP, ARP-table collection and flow data are for.

Reading a stalled session. stalled means the daemon stopped reporting progress. It usually means the daemon process died or lost its route mid-scan. The session is not lost; the next scheduled run picks the range back up.

Hosts and services

The list is searchable by hostname and FQDN and shows addresses, device type, operating system and service count. It is capped at 200 rows — narrow with the search box or the site picker rather than scrolling.

A host page collects everything known about one machine: addresses, interfaces, open ports, detected services with versions, TLS certificates, vulnerabilities and a change feed.

How services are identified. A port being open is not a service. Loomscope matches a signature — a pattern combining port, protocol, an HTTP endpoint and an expected response fragment — and records a confidence score. grafana is identified by /api/health returning something containing grafana, not by port 3000 being open.

Confidence matters. A service matched by banner is less certain than one matched by an endpoint response. Confidence is shown, and it propagates into CVE matching, where a low-confidence version guess produces a lower-confidence finding.

Topology

Four views over the same inventory, each answering a different question.

Regenerating. Views are generated snapshots, not live queries. Regenerate rebuilds them from current inventory. If a site is selected, only that site's view is rebuilt.

Positions are yours. Drag a node and the position is saved. A regeneration preserves it. Locking a topology stops regeneration from moving anything.

Reading the application view honestly. When flow data exists, edges are real observed dependencies. When it does not, Loomscope draws lighter co_hosted edges between services on the same host — a placeholder, not a claim that they communicate. Once NetFlow or sFlow is collecting, real edges replace them.

Exports. Any view exports to Mermaid (for a Markdown document) or draw.io (for editing). Share creates a read-only link that needs no account — useful for an auditor, and revocable.

Vulnerabilities

Loomscope matches discovered services against OSV and NVD advisories.

Filtering is by severity and state. The default shows open and acknowledged findings, ordered by severity then age.

States.

Matched via tells you how much to trust a finding. cpe means a structured product-and-version match and is reliable. A banner-derived match is a heuristic and is where false positives concentrate.

Marking a false positive is useful work. It removes noise permanently and records that the finding was examined rather than ignored.

Air-gapped operation. CVE data comes from a local mirror. If the mirror is stale, matches are stale — check the ingest worker's last successful sync.

Certificates

Every TLS handshake the daemon performs records the certificate.

Filters cover expiry windows (30, 60, 90 days) and self-signed certificates. The expiry column colours by urgency, and expired certificates are shown as overdue rather than hidden.

Two questions this answers well: what expires next month, and what is still using a self-signed certificate we forgot about.

History and change tracking

Snapshots freeze the inventory at a point in time. One is taken daily; you can also take one manually before a change window.

Diffs compare any two snapshots and report what was added, removed or changed, per entity. This is the fastest way to answer "what changed since Friday".

The change feed on a host page shows that host's history without needing to pick snapshots.

PDF attestation. Any snapshot exports as a signed-looking PDF report listing the inventory at that instant — intended for auditors who want evidence of state on a date.

Activity density. The 60-day strip on the History page shows snapshot frequency, which is a quick way to notice the scheduler stopped running.

Sites

Sites let one Loomscope serve several locations without mixing them up.

The site picker in the header scopes every page. "All sites" shows everything; picking one filters hosts, networks, vulnerabilities, certificates, topology and history. The choice persists across sessions.

Binding a daemon to a site can be done from the site page, or by setting LOOMSCOPE_DAEMON_SITE_CODE on the daemon before it registers. If both are set, the UI assignment wins.

Per-site dashboards summarise one location: hosts, services, open vulnerabilities, certificates, its daemons and recent activity.

Per-site roles let someone be a viewer across the organisation but an editor for one site. Overrides can only raise permissions — your organisation role is the floor. When an override applies, a scoped: badge appears next to the site picker.

Cloud inventory

Loomscope discovers AWS and Kubernetes resources from the control plane, so daemon hosts never hold cloud credentials.

AWS covers EC2, VPC, RDS, ELB, Lambda, EKS and security groups. Kubernetes covers nodes, pods, services and ingresses.

Add an account with read-only credentials, and sync on demand or on a schedule. Cloud resources are correlated with scanned hosts where they match, so an EC2 instance and the host discovered at its private address become one thing rather than two.

Custom service signatures

Loomscope ships signatures for common services and lets you add your own without rebuilding anything — which matters for in-house applications no vendor will ever fingerprint.

Drop a YAML file into /etc/loomscope/signatures.d/ on the daemon:

version: 1
service:
  id: internal-auth-service
  name: Internal Auth Service
  description: In-house OIDC provider
  category: Web
  vendor: ACME Corp
  confidence_default: 85
  pattern:
    all_of:
      - port: { protocol: tcp, number: 8443 }
      - endpoint:
          port: { protocol: tcp, number: 8443 }
          tls: true
          path: /healthz
          expect: "auth-service v"

Send SIGHUP to the daemon to reload. Validation is strict: an unknown field or a bad enum fails at load with an explicit error rather than silently ignoring the file.

Patterns compose with all_of, any_of and not, and can match on port, HTTP endpoint response, MAC vendor, gateway status or subnet type.

The AI assistant

Optional, off unless a provider is configured, and it can run entirely locally against Ollama if data must not leave the network.

It has read-only access to your inventory and is good at questions that would otherwise be several filtered searches: which hosts gained a new service this week, what is exposed on the DMZ subnet with a critical CVE, summarise what changed on this host.

Two honest limitations. It answers from the inventory, so anything Loomscope has not discovered it cannot know. And a per-organisation monthly token budget applies to hosted providers — when it is exhausted, the assistant stops rather than generating a surprise invoice.

Roles and permissions

Per-site overrides raise a role for one site and never lower it. Your organisation role is always the floor.