Integration guides

Connect Hetzner Object Storage

Detectant connects to private Hetzner Object Storage buckets with read-only S3 credentials. It supports the fsn1 (Falkenstein), nbg1 (Nuremberg) and hel1 (Helsinki) locations. Detectant derives the endpoint and signing region from the selected location.

Before you connect

  1. In Hetzner Console, create dedicated S3 credentials for Detectant. Save the secret key when it is shown; Hetzner does not show it again.
  2. Restrict those credentials to the bucket and optional prefix with a bucket policy. Since Hetzner credentials can access every bucket in their project by default, we recommend that you create the credentials in a separate project and grant that principal read-only access from the project that owns the bucket. Check this part of the Hetzner docs for more info on restricting key access.
  3. Keep a separate administrative key in the bucket’s project so you can apply and update its policy.
  4. Note the bucket location and the project ID that owns the dedicated credentials.

The dedicated key needs only s3:ListBucket, s3:GetObject and s3:GetObjectVersion. The last action is required by Hetzner when the bucket has versioning enabled. Detectant does not need write or delete access.

For a whole bucket, apply a policy like this with an administrative S3 tool. Replace every placeholder first.

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Sid": "DetectantList",
6      "Effect": "Allow",
7      "Principal": {
8        "AWS": "arn:aws:iam:::user/p<CREDENTIAL_PROJECT_ID>:<DETECTANT_ACCESS_KEY>"
9      },
10      "Action": "s3:ListBucket",
11      "Resource": "arn:aws:s3:::<BUCKET>"
12    },
13    {
14      "Sid": "DetectantRead",
15      "Effect": "Allow",
16      "Principal": {
17        "AWS": "arn:aws:iam:::user/p<CREDENTIAL_PROJECT_ID>:<DETECTANT_ACCESS_KEY>"
18      },
19      "Action": ["s3:GetObject", "s3:GetObjectVersion"],
20      "Resource": "arn:aws:s3:::<BUCKET>/*"
21    }
22  ]
23}

To restrict Detectant to a prefix, add this condition to the list statement and replace the object resource with arn:aws:s3:::<BUCKET>/<PREFIX>/*:

1"Condition": {
2  "StringLike": {
3    "s3:prefix": ["<PREFIX>", "<PREFIX>/*"]
4  }
5}

Bucket policies are security-sensitive. Test the policy with the dedicated key before removing existing administrative access. Hetzner documents its principal format and same-project alternative in its S3 credentials guide.

Connect the bucket

In Dashboard → Integrations, choose Add integration, select Hetzner, then enter the location, bucket, optional prefix, access key ID and secret access key.

Choose New files only to baseline existing objects without scanning them. Choose Existing and new files to preview the eligible existing-object count and remaining monthly allowance. Existing objects are not released for scanning until you confirm the preview. Objects beyond the current allowance remain queued until the next billing period.

Setup verifies list, metadata and object-read permission. For an empty scope, setup can verify only list permission; object-read permission is checked when an object appears.

Credentials are encrypted and never returned. Replacing credentials verifies the replacement before deleting the old encrypted credentials and schedules an immediate check.

Monitoring behavior

Hetzner Object Storage does not provide S3 bucket notifications, so Detectant checks the configured scope every five minutes. New or changed objects are scanned once; unchanged objects are not rescanned. Directory-marker objects are ignored.

  • Baselining: Detectant is building the initial inventory.
  • Healthy: The baseline or latest check completed. The dashboard shows the last and next check.
  • Temporary failure: A provider or network request failed. Detectant keeps the last successful check visible and retries with bounded backoff.
  • Credentials rejected: Replace revoked, incorrect or insufficient credentials.
  • Object limit exceeded: The scope exceeds the first-release limit of 100,000 listed entries. Use a narrower prefix or bucket.
  • Allowance paused: Queued scans resume at the next billing-period boundary without downloading object content first.

Object size, versions and encryption

S3 objects can be up to 500 MB on Free and 2 GB on paid plans. These limits are separate from direct API uploads. Larger objects are recorded as too large without being scanned. Detectant stages readable content only for the scan and immediately removes its temporary copy.

Detectant scans the current object revision only. Overwriting a key makes its new current revision eligible; historical versions are not enumerated. Hetzner supports customer-provided encryption keys (SSE-C), but Detectant does not accept or retain those keys, so SSE-C objects are not supported. Detectant does not change object locks, retention settings or bucket contents.

Troubleshooting

  • Confirm the selected location matches the bucket: fsn1, nbg1 or hel1.
  • Confirm the key can list the exact configured prefix and read at least one object in it.
  • If an empty scope connects but later reports unreadable objects, add s3:GetObject and, for a versioned bucket, s3:GetObjectVersion.
  • If the provider returns temporary errors, leave the integration active; Detectant retries conservatively and shows the next attempt.
  • After rotating a key, use Replace credentials rather than deleting the integration.