Skip to content

Instrument pipeline security and data handling

Instrument connectivity crosses the boundary between laboratory networks and FlaskTrack. Configure agents and connectors as controlled infrastructure rather than ordinary desktop utilities.

Supported instrument agent platforms and security context
Deploy agents on supported systems with least-privilege access and organization-approved network controls.

Outbound connection model

For a FlaskTrack cloud deployment, the Instrument Agent initiates the connection to FlaskTrack.

This avoids requiring:

  • public SMB or NFS shares;
  • inbound firewall rules to laboratory workstations;
  • public exposure of private instrument APIs;
  • direct FlaskTrack cloud access to private RFC1918 addresses.

Agent credentials

Instrument Agent keys begin with:

ftia_

Treat the key like any other machine credential.

Do not:

  • commit it to Git;
  • paste it into tickets or public chat;
  • include it in screenshots;
  • reuse a revoked key;
  • share one key between unrelated machines when separate agents can be created.

Rotate a key when the machine role changes or the credential may have been disclosed.

Configuration file permissions

On Unix-like systems, restrict the bootstrap configuration so ordinary users cannot read the machine key.

The supplied agent initialization writes restrictive permissions on supported Unix platforms, and the supplied Windows installer restricts the installed configuration ACL to SYSTEM and Administrators.

Your local security policy remains authoritative.

HTTPS

Use HTTPS for production FlaskTrack endpoints.

The agent accepts loopback HTTP for local development. Do not enable insecure HTTP for production SaaS traffic.

No FlaskTrack credential is sent to vendor endpoints

Local vendor connections such as Opentrons are separate from the FlaskTrack upload connection. The FlaskTrack agent key is intended for FlaskTrack machine authentication and should not be forwarded to instrument/vendor URLs.

Network-share credentials

Do not place SMB/NFS usernames or passwords in general connector settings unless a specific approved integration explicitly requires it.

Prefer operating-system or infrastructure-managed mounts and service identities.

Raw artifacts

The agent calculates a SHA-256 fingerprint before upload, and FlaskTrack preserves artifact identity as part of the ingestion record.

Keep the source artifact and parsed result conceptually separate:

Original instrument artifact
        ↓
Ingestion record
        ↓
Parser
        ↓
Structured run

A parsed run is not a replacement for the original source artifact.

Local spool

The agent stages pending artifacts in a local spool before upload. Protect the state directory according to the sensitivity of the laboratory data being processed.

Consider:

  • filesystem permissions;
  • full-disk encryption;
  • backup policy;
  • endpoint security;
  • local retention procedures;
  • secure decommissioning of retired agent hosts.

Dead-letter data

Artifacts rejected permanently by the server may remain under the agent's dead-letter directory for investigation.

Review and clear these records under an approved procedure; do not assume they disappear automatically.

Review-controlled runs

FlaskTrack locks mappings after instrument-run review begins. Accepted and Rejected runs remain review-locked.

This helps prevent a reviewed scientific result from changing because a source mapping was edited afterward.

Electronic signatures

Where instrument run acceptance or rejection uses FlaskTrack electronic signatures, signature authorization is tied to the controlled run decision. Rejection reasons are part of the signed decision payload.

Operational recommendations

For production laboratories:

  1. use a dedicated or controlled machine identity for the agent;
  2. restrict who can administer that machine;
  3. keep the agent binary and configuration under change control appropriate to your environment;
  4. document which instruments and shares each agent can access;
  5. review agent and connector errors;
  6. rotate credentials during machine replacement or suspected compromise;
  7. verify parser changes before production use;
  8. preserve objective evidence when the pipeline is part of a regulated workflow.

Transport-specific credentials and controls

The Rust agent does not require a Python runtime. Native collectors still require the appropriate lab-network access and service permissions.

Connection Credential/trust configuration
REST/vendor HTTP bearer_token_env or header_env; host variables contain secrets
SFTP Verified host_key_sha256; local key file or password-variable reference
MQTT TLS Trusted CA file; optional paired client certificate/key; password variable
Serial OS device/COM-port permissions and safe control-line behavior
SDK/Custom Trusted installed executable, service permissions, vendor SDK access

Top-level credential_reference is not delivered/resolved by this agent. A reference alone will not authenticate these sources. Protect local private keys and service environment configuration; keep secret values out of connector JSON, screenshots, and logs.

HTTP redirects are refused. Pagination links must remain on the original URL origin so credential headers are not sent to another endpoint. SFTP verifies a pinned host-key fingerprint; verify it independently before entering it. MQTT over mqtts:// requires the configured CA trust file.

SDK/custom adapters run under the service account with literal arguments and no shell expansion. Restrict who can edit their executable paths. The adapter must manage any descendant processes and close stdout; the agent times out/kills its direct child only.

Protect the entire agent state directory, including native captures, upload spool, deduplication markers, and dead-letter artifacts. Collection limits are per artifact; total local disk usage is not capped by this update.