Connector security

The Pareo Connector is a standalone program that you run inside your network. It reads Teamcenter and SAP, and it sends the result out to Pareo. Pareo never connects into your network (outbound-only). This page is for your IT and security team. Read it before the install.

What runs where#

The connector makes outgoing HTTPS calls to one host. Nothing calls it. There is no open port, no VPN and no allow-listed Pareo address on your side.

What leaves your network#

• The records your administrator allowed in the profile: material and product numbers and names, the properties bound for the compliance rows, and bill of materials positions.
• Only released revisions from Teamcenter, with their release status and release date.
• Only the systems you allowed when you created the connector. Pareo refuses data from any other system, whatever the connector sends.
• Status information: version, host name, address, checks, disk and spool figures, and the settings it runs with. These settings never include a secret.

What never leaves your network#

• Logins, passwords and secrets for Teamcenter, SAP or the proxy.
• The private key of the connector.
• Files, drawings, CAD data and anything outside the allowed profile fields.
• Property values in the connector log. Logs hold record ids, counts and errors only.

The connector reads Teamcenter through the Core and Query services only. It opens one session for each run and always logs out.

Signing and keys#

• On first start, the connector makes its own Ed25519 key pair. The private key never leaves the virtual machine.
• Each call carries the connector id, a time stamp, a single-use number and a signature over the method, the path, the time stamp, the number and a hash of the body.
• Pareo refuses a call with a time more than 5 minutes off. It refuses a number it saw in the last 10 minutes. A copied request does not work twice.
• The key fixes the organization and the allowed systems. One organization's key cannot write for another organization.
• Pareo signs the extraction profile with its own key. The connector accepts only a signed profile. To keep the profile fixed, set profile_pinned: true in the config file. The connector then keeps its current profile and refuses a remote profile change or unpin from Pareo. Only a change of the config file lifts the pin. Alternatively, set profile_file to a local profile file that you control.
• The connector does not follow HTTP redirects. teamcenter.url, sap.url and sap.token_url must use https. Plain http passes for localhost only.

Joining and approval#

1. An administrator creates the connector in Pareo (Settings → Connections → Pareo Connector) and downloads the install package.
2. The package holds a setup key. The key works once, is valid for 30 days and is stored only as a hash.
3. The connector starts, makes its key pair and joins with the setup key. It now waits for approval. There is no deadline. It sends no data, only a call every minute.
4. The administrator sees the host name, the address, the version and the key fingerprint. IT reads the fingerprint from the connector log. The two must match. Then the administrator approves.
5. A setup key used twice is refused and raises an alert. A key used from a second host is refused and raises an alert. Only the approved host is accepted. The host name is the one of the virtual machine: the compose file mounts its /etc/hostname read-only, so a recreated container keeps it.

An administrator can pause a connector at any time. Pause stops data and keeps the calls. Revoke stops all data at once. Rows already synced stay in Pareo with their sync time.

An administrator can also replace the key of a connector in any state but revoked. The old key stops working at once. Pareo issues a new setup key. Your IT puts it into ./secrets/setup.key and restarts the container. The connector sees the new key, sets its old key pair aside as connector.key.old in its state volume, makes a new pair and joins again. The administrator approves it again. The rows it synced stay.

Updates and image verification#

• Pareo does not push updates. Your IT pulls a new image and restarts the container.

• When a newer version is released, the connector page shows "update available". The administrators of your organization get one notification per release.

• Pareo has a minimum supported version. A connector below it still reports its status, so the connector page shows it as "no longer supported". Pareo takes no data from it and gives it no requests. The connector log says that it sends no data because its version is no longer supported (unsupported_version). After IT updates the image, the connector syncs again on its own.

• The image has a pinned digest. It is built on a minimal base image without a shell. It runs as a non-root user, with a read-only file system, no added capabilities and no-new-privileges.

• Each image is signed with a dedicated Pareo signing key. An SPDX software bill of materials is attached to it. Verify both before you run the image:

  cosign verify --key pareo-connector.pub <image>@sha256:<digest>
  cosign verify-attestation --key pareo-connector.pub --type spdxjson <image>@sha256:<digest>
  

  The install package names the image. Save the following public key as pareo-connector.pub:

  -----BEGIN PUBLIC KEY-----
  MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEr7Fj0KSVaqd5lZvOxYIA9h4XLD31
  +TkqizG9KrSd4df2IJIC3RBViHU/wP+KO9XC7g1LkZIT6DkRHasJAWSbyA==
  -----END PUBLIC KEY-----
  

  Pareo publishes this key in its public documentation. A key from any other source is not the key of Pareo.

Logging without values#

• The console shows one readable line per event, for example ok approved by Pareo or fix sap login refused (401), check /run/secrets/sap_client. The log file in the state volume and the lines the connector sends to Pareo are JSON. With log: { format: json } in the config file the console shows JSON lines too. A value read from Teamcenter or SAP never enters the logger, in either form.
• A debug log level is off by default. An administrator can ask for debug for a short time. Debug lines still carry record ids only.
• A diagnostics request returns counts and errors, never record contents.

Failure behaviour#

• If Pareo is not reachable, the connector keeps reading into its disk spool and uploads the batches in order when Pareo answers again. The default spool limit is 5 GB or 14 days.
• If the disk is full, the connector stops reading and keeps uploading.
• If the connector restarts or crashes, it continues from the spool and its checkpoint. A batch sent twice is stored once.
• If a source times out, the connector halves its page size and tries again. It honours a "too many requests" answer from Pareo.
• A run that stops early is marked partial or failed with its gaps. A partial run never deletes rows in Pareo. Only a complete full read can withdraw rows that are gone from the source, and only for numbers that source stated before. A row from a file, a document or a person stays.
• Pareo alerts your administrators when a connector is silent, a run fails, the disk is full or a check fails.

What IT sets up#

The connector has two test commands. check tests the config, the secrets, the network, TLS and the logins. dry-run counts what a run would read. Neither sends data.

The compose file sets a health check (/connector health), mem_limit 2g, pids_limit 256 and bounded json-file logs.

Network#

Allow the DNS names where your firewall can. ingest.pareo.ai resolves to one reserved, static address. If your firewall takes only IP addresses, allow the address the name resolves to. A connector for a staging environment calls ingest-staging.pareo.ai instead of ingest.pareo.ai.

Proxy#

• The proxy setting applies to the calls to Pareo only. Calls to SAP and Teamcenter go direct.
• The connector supports a proxy with Basic login or no login. It does not support NTLM or Kerberos proxies.
• For Basic login, put the user name and password in the proxy URL, for example http://user:password@proxy.corp.local:8080. The connector removes them from every status report.
• For an NTLM or Kerberos proxy, use one of two options: exempt ingest.pareo.ai from proxy authentication, or run a local helper (for example CNTLM) that does the NTLM login and set proxy to the helper.
• If a proxy inspects HTTPS, mount the company root certificate and set ca_bundle. See the install steps.
• A proxy that changes the body of a request breaks the signature, and Pareo refuses the call. Exempt ingest.pareo.ai from such a proxy.

Image from your own registry#

You can serve the image from your own registry (Harbor, Nexus, Artifactory) instead of pulling it from Pareo.

1. Copy the image with its digest. --all copies every platform:

   skopeo copy --all docker://<image>@sha256:<digest> docker://your-registry.example/pareo/connector:<tag>
   

   Or use crane copy <image>@sha256:<digest> your-registry.example/pareo/connector:<tag>.

2. Copy the signature and the bill of materials too. cosign copy <image>@sha256:<digest> your-registry.example/pareo/connector:<tag> copies the image, its signature and its attestations in one step.

3. Verify the copy against the public key on this page. The digest must be the same:

   cosign verify --key pareo-connector.pub your-registry.example/pareo/connector@sha256:<digest>
   

4. In compose.yaml, change the image line to your registry and keep the digest. Keep PAREO_IMAGE_DIGEST equal to the digest.

SAP technical user#

The connector reads SAP over OData and only reads. Give the user display rights (authorization activity 03) and no change rights.

The long-text service is optional. The connector reads it only if the profile names a long-text service and the characteristic values have a long-text id. Without it, the connector sends the values without their long texts and counts the long texts it did not read.

The connector logs in in one of two ways. Set sap.auth to choose.

sap.client_file holds the client id (or user) on line 1 and the secret (or password) on line 2. sap.token_url defaults to <sap.url>/oauth/token. Set it if your token service is on another address. Both URLs must use https.

Teamcenter user#

The connector calls these Teamcenter SOA operations through the JSON REST interface. It uses the Core and Query services only.

The user needs read access to the saved query and to the item revisions it returns. It needs no write access. A full read reads up to 250,000 revisions for each saved query.

Install#

Install and run the Pareo Connector has the full steps with screenshots, the checklist for the VM and the technical users, updates, and every error message. The short form:

1. Unzip the install package into one folder on the virtual machine. It holds compose.yaml, config/connector.yaml, security-sheet.md (this page) and the folder secrets with setup.key in it. The compose file mounts ./config and ./secrets read-only.
2. Verify the image signature (see above).
3. Open config/connector.yaml. Fill in the address and the secret file of each system. Remove the # in front of proxy or ca_bundle only if you need them.
4. Put the logins into ./secrets. tc_user and sap_client each hold two lines: the user (or client id) on line 1 and the password (or secret) on line 2.
5. Check the config: docker compose run --rm connector config check. The answer is ok config read, no secrets in it.
6. Start it: docker compose up -d. With Podman, run podman-compose up -d. With rootless Podman, add :Z to each bind mount in compose.yaml except /etc/hostname, as the comment in the file shows.
7. Read the log: docker compose logs connector. The first line names the version and the digest that compose.yaml pins, for example ok connector 1.0.4 (image sha256:45b57bbd4784, as pinned in compose.yaml). It is the value of PAREO_IMAGE_DIGEST, not a check of the running image. To check the running image, compare docker image inspect --format '{{index .RepoDigests 0}}' <image> with the digest you verified. Expect ok key pair created on this VM, fingerprint ..., ok setup key accepted and .. waiting for approval in Pareo. Read the fingerprint to the administrator.
8. After the approval the log shows ok approved by Pareo, organization ..., may send: ... and the first checks. To test again, run docker compose run --rm connector check. To count what a run would read, run docker compose run --rm connector dry-run. Neither sends data.
9. If the virtual machine reaches the internet through a proxy, set proxy in config/connector.yaml. If a firewall inspects HTTPS, mount the company root certificate (the compose.yaml shows the line) and set ca_bundle to its path. A change of config/connector.yaml is read within a minute; a change of compose.yaml needs docker compose up -d.

Questions IT answers before the install#

1. Which virtual machine hosts the connector, and who patches it?
2. Does the virtual machine reach ingest.pareo.ai on port 443, directly or through a proxy?
3. Does a firewall inspect HTTPS? Which root certificate must the connector trust?
4. Which container runtime runs it, Docker or Podman?
5. Which Teamcenter technical user reads the saved query? Does it have read rights only?
6. Which SAP technical user reads the bills of materials? Does it have read rights only?
7. Where do the secret files live, and who can read them?
8. Who verifies the image signature, and who updates the image?
9. How large is the disk for the spool?
10. Who sees the alerts about a silent or failing connector?
11. Do you start with test systems, and is a separate connector for production planned?

Questions about this page go to Pareo support: .