Extend authorization scriptlet (certificate and instance details)

[fatyzzz]

Is there an existing issue for this?

• There is no existing issue for this feature

What are you currently unable to do

Currently, Incus certificate-based access control works at the project level. When using incus config trust add --restricted --projects <project>, the certificate gains access to all instances within that project.

In CI/CD environments (GitLab CI, GitHub Actions, etc.) with Ansible automation, this creates a security concern: if a runner is compromised, the attacker gains exec access to ALL instances in the project, not just the ones that specific CI job needs.

For example, I have a project with 15 instances including sensitive ones (Vault, GitLab, Keycloak) and less sensitive ones (Grafana, YouTrack). I want my deploy-grafana CI job to only have exec access to the grafana instance, not to vault or gitlab.

The current workarounds are:

• Multiple projects — splits infrastructure awkwardly, complicates networking and management
• OpenFGA integration — requires deploying and maintaining a separate authorization service, significant operational overhead for simple use cases
• SSH keys per instance — works but adds complexity (key management, rotation, sshd in containers) that Incus exec elegantly avoids

What do you think would need to be added

Add the ability to restrict certificate access to specific instances, not just projects. Something like:

# Restrict certificate to specific instances within a project
incus config trust add ansible-grafana \
  --restricted \
  --projects myproject \
  --instances grafana,monitoring

# Or using instance patterns
incus config trust add ansible-runners \
  --restricted \
  --projects myproject \
  --instances "gitlab-runner-*"

This would allow the certificate to:

• List/view only specified instances
• Exec/console/files access only to specified instances
• No access to other instances in the project

This fits well with the existing --restricted model and would make Incus much more suitable for secure CI/CD automation without requiring external authorization systems.

[stgraber]

Did you try the authorization scriptlet?
https://linuxcontainers.org/incus/docs/main/authorization/#scriptlet-authorization

[fatyzzz]

Did you try the authorization scriptlet? https://linuxcontainers.org/incus/docs/main/authorization/#scriptlet-authorization

I looked into the authorization scriptlet approach, but I think per-instance restriction would be much better as a native feature (extending the existing --restricted model) rather than a scriptlet workaround. Here's my reasoning:

Why scriptlets don't fit this use case well:

The authorize() function only receives details.Username which is the certificate's SHA256 fingerprint. With short-lived certificates (Vault PKI, TTL 10-15 min), the fingerprint is different on every issuance. There's no way to write a static scriptlet that maps ephemeral fingerprints to allowed instances.

The possible workarounds are all fragile:

• Dynamically rewrite the scriptlet on every CI job to inject the new fingerprint → instance mapping. Race conditions with concurrent jobs, requires privileged access to server config.
• Expose CN or cert name in details — would work, but still means every user has to write and maintain Starlark code for what is essentially a simple access list.

Why native --instances makes more sense:

1. Consistency with existing model. Incus already has --restricted --projects which limits certificates to specific projects. Adding --instances is the natural next step in the same pattern. Users already understand this model.

2. Short-lived certificate friendly. The restriction is bound to the trust store entry, not to a hardcoded fingerprint in a scriptlet. When a CI job adds a new cert with --restricted --projects myproject --instances grafana, it just works regardless of the fingerprint.

3. No code to maintain. Scriptlets require every admin to write, test, and debug Starlark authorization logic. A native flag is declarative — add it once and it's enforced by Incus itself.

4. Concurrency safe. Multiple CI jobs adding different restricted certificates with different --instances constraints works naturally. No shared mutable state like a scriptlet that needs atomic updates.

5. Auditability. incus config trust list would show exactly which certificate has access to which instances. With scriptlets, you have to read and understand the Starlark code to know who can access what.

The use case is straightforward and common: CI/CD systems (GitLab CI, GitHub Actions) running Ansible deployments where each job should only exec into its target instance. The existing --restricted --projects is 90% of the way there — --instances would complete it.

Would you consider adding this as a native restriction alongside --projects?

[fatyzzz]

Understood, thanks for looking at it.

The main issue is that none of the current options are production-ready for this use case. The scriptlet approach doesn't work with short-lived certificates (Vault PKI, rotating fingerprints) — authorize() only sees the fingerprint, so there's no stable identity to match against without dynamically rewriting the scriptlet on every CI job. Splitting into multiple projects breaks networking and is a management nightmare. And running sshd in every container just to get per-instance access control feels like a step backwards.

So right now there's effectively no clean path to per-instance access control in production, which is a real blocker for secure CI/CD setups. Native --instances would close this gap completely. Happy to help test if this ever moves forward.

UPD: SSH is technically an option too, but then we lose the Incus integration entirely — no incus exec, no incus file, no native lifecycle management. At that point we're just treating containers as dumb VMs and working around Incus rather than with it.

[stgraber]

I'm not super keen on extending the certificate config right now.

I think your best bet at the moment is to extend the scriptlet logic. It's easy to expose functions to scriptlets, so we could just export a function to get details from a certificate fingerprint which would then give you the name property as a more stable identifier that you can check against.

[fatyzzz]

Thanks for considering this, that sounds like a reasonable compromise! Exposing certificate details to the scriptlet would definitely solve the core issue — right now there's no way to map an ephemeral fingerprint back to a stable identity, so this would make the scriptlet approach actually viable with short-lived certificates.

A few things that would still be less ideal compared to native per-instance restrictions, just to keep on your radar:

• The scriptlet needs to be manually updated every time a new instance or access rule is added, whereas a declarative flag would be self-contained in the certificate config.
• There's no easy way to audit who has access to what — with native restrictions it would be visible in incus config trust list, but with a scriptlet you have to read and understand the Starlark code.
• It's a single shared scriptlet for the entire server, so the authorization logic for all certificates and instances lives in one place, which can get complex over time.

That said, this is a big improvement over the current situation where the scriptlet simply can't work with rotating certificates. I'd be happy to test it once it's available. Thank you!

[stgraber]

The scriptlet needs to be manually updated every time a new instance or access rule is added, whereas a declarative flag would be self-contained in the certificate config.

That part isn't necessarily true. You could add config options user.XYZ on the instance itself which the scriptlet could then review to manage access.

[stgraber]

There's no easy way to audit who has access to what — with native restrictions it would be visible in incus config trust list, but with a scriptlet you have to read and understand the Starlark code.

Yeah, that's a bit of a double edge sword, on the one hand, you can't easily tell what a given cert has access to, but on the other hand you can look at one script and know it will be applied identically to all certificates.

[stgraber]

It's a single shared scriptlet for the entire server, so the authorization logic for all certificates and instances lives in one place, which can get complex over time.

Yeah, but that's where being able to use something somewhat generic in the scriptlet would be beneficial. If you put the list of allowed certificate names in an instance config, say user.rbac.exec = NAME1,NAME2, then it becomes pretty easy for the scriptlet to:

1. Check if the permission is can_exec on an instance
2. If it is, pull the instance config to look for a user.rbac.exec
3. If present, pull the details on the current certificate
4. If the certificate name is in the list of names in user.rbac.exec then allow access

That would effectively let you implement the kind of logic you're looking for in a way that requires little to no changes to the scriptlet over time.

[fatyzzz]

It's a single shared scriptlet for the entire server, so the authorization logic for all certificates and instances lives in one place, which can get complex over time.

Yeah, but that's where being able to use something somewhat generic in the scriptlet would be beneficial. If you put the list of allowed certificate names in an instance config, say user.rbac.exec = NAME1,NAME2, then it becomes pretty easy for the scriptlet to:

1. Check if the permission is can_exec on an instance
2. If it is, pull the instance config to look for a user.rbac.exec
3. If present, pull the details on the current certificate
4. If the certificate name is in the list of names in user.rbac.exec then allow access

That would effectively let you implement the kind of logic you're looking for in a way that requires little to no changes to the scriptlet over time.

That's actually a really clean approach, I hadn't thought about using user.* config on instances as the access list. A generic scriptlet that just checks user.rbac.exec against the certificate name would cover my use case perfectly and wouldn't need any maintenance as instances are added or removed.

Looking forward to the certificate detail function being available in scriptlets — happy to test it as soon as it lands. Thanks for working through this!