Projects and folders

Ctadel files what it reads by project, and you file your accounts and repositories in folders. The project is the technical unit: every finding carries one. The folder is your own layout: it groups cloud accounts and Git repositories in a tree, and serves to filter the screen and to restrict roles.

The project

A project is a cloud-native scope: the identifier of the connected account and, where the cloud exposes them, the projects discovered inside that account. Every configuration, secret, data, Kubernetes, host or attack-path finding carries the identifier of the project its resource belongs to. Filters and permissions rest on that identifier.

The selector at the top of the screen lists "All Projects", then "Folders (N)" and "Projects (N)". Choosing a project restricts every page to its resources; choosing "All Projects" lifts the filter. The choice follows the session and applies to the dashboard, the finding lists, the inventory and the graph.

The folder

A folder is a node of a free tree, up to 10 levels deep. It holds cloud accounts (one whole account per leaf) and Git repositories. Two folders under the same parent cannot share a name.

Management happens in "Settings", "Integrations" tab, "Folders" sub-tab. Reading requires the "Read" permission of the "Settings" domain, changing requires "Update". You can create a root folder or a sub-folder, rename it, move it, delete it, and drop an account or a repository into it. A separate card lists the cloud accounts and repositories not attached to any folder. A folder can only be deleted when empty: no sub-folder, no account, no repository.

A system folder named "Unscoped" exists from installation. It cannot be renamed, moved or deleted. Every repository discovered by a Git scan is filed there by default, and a repository you remove from a folder goes back to it. Since it is a real folder, a role can be scoped to it: that role then has access to every repository not yet filed.

Choosing a folder in the header selector selects every project of the accounts it holds, plus the repositories of its subtree; sub-folders are included. A folder holding no cloud account is greyed out in the selector.

The .ctadel.yaml file

A Git repository can declare its own folder. The .ctadel.yaml file at the repository root, already used for rule suppressions, accepts a folder field:

version: 1
folder: "Production/Europe/France"

The path is slash-separated. On each scan of the default branch, the repository is filed under that folder; missing folders along the path are created. This declaration is authoritative: it overrides a move made in the interface.

In the other direction, moving a GitHub repository in the interface opens a pull request in the repository, on a ctadel/set-folder-<timestamp> branch, that adds or replaces the folder: line of the file while keeping the rest of its content. The repository shows "PR en attente" until the pull request is merged and the next scan confirms the folder; it then shows ".ctadel". A repository filed by hand without a file shows "manuel".

Effects on restricted users

A role can be scoped to projects ("Project scope") or to folders ("Folders") when it is created or edited in the "Roles" tab. The interface hint sums it up: "A role scoped to a folder gives access to every account in its subtree. Leave empty to use only the project scope above."

When a session opens, each folder of a role is expanded into the list of projects of the accounts in its subtree, and each repository of the subtree is added to the list of allowed repositories. The user sees only those projects and repositories in the finding lists, the Git scan reports, the secrets and the vulnerabilities. A role with neither project nor folder is global.

A role scoped to a folder that holds no cloud account, such as "Unscoped", stays restricted: it grants access to no cloud project, only to the folder's repositories. The user menu, under "Switch Role", shows one entry per role and scope pair, with "All projects" for a global role.

An account added later to a folder is visible to the roles scoped to that folder from their next session; no role setting needs to be redone.

Limits

• Writing the .ctadel.yaml file back from the interface works only for GitHub repositories connected through the GitHub App; for a GitLab repository, the move in the interface is recorded on the Ctadel side without a pull request, and the next scan of a file that declares another folder will override it.
• A folder is a set of whole accounts: an account cannot be split between two folders, and a project discovered inside an account cannot be filed separately.
• Folder scoping applies to finding lists and detail pages; the aggregation of the compliance page, in internal validation, counts by project and does not know folders.
• Folders carry no permissions or settings of their own: they have no alert rules, frequency or retention. Alert rules filter by project, not by folder.
• Folders created from a .ctadel.yaml file are never deleted automatically, even when no repository declares them any more.
• Version 1 is the only accepted version of .ctadel.yaml; an invalid file makes the reading of the folder declaration and of the suppressions fail.