Workspaces, Projects and Access
Three ideas structure everything else in ShieldedStack. Workspaces decide where policy applies, projects decide who a request belongs to, and members decide who can change any of it.
Workspaces
Section titled “Workspaces”A workspace holds proxy policy, package filters, vulnerability exceptions, alert history, package activity, notification channels, and API keys. Everything in the console is read through the workspace selected in the sidebar.
Use separate workspaces when environments need genuinely different answers. Production tightening its block level should not disturb a sandbox, and a permissive allow list for a research team should not become the organisation’s policy. Splitting also keeps the alert queue meaningful: alerts from a sandbox nobody ships from do not bury alerts from a release pipeline.
Do not split further than you can maintain. Every workspace is a policy that someone has to keep current, and three well-tended workspaces beat a dozen that drifted.
Creating and renaming workspaces requires the Manage workspaces permission or workspace admin rights.
Projects
Section titled “Projects”A project is the name attached to package activity. Projects are not created from a form: they come into existence when you generate an API key and give it a project name, and everything that key pulls is recorded against that name.
Name them after something real and durable: a repository, a service, a pipeline. checkout-api, web-frontend, data-pipeline. Valid characters are letters, numbers, hyphens, underscores, and periods.
The names matter more than they first appear, because they are what every other view filters by. A workspace where half the traffic arrives under test or ci cannot answer which service is exposed to a vulnerability, which is the question you will eventually need it to answer.
Project Metadata
Section titled “Project Metadata”The Projects page lists tracked projects, their package counts, and their metadata. For each project you can add:
- a description, so a name that made sense to its author is legible to everyone else, and
- metadata as key and value pairs, such as
departmentandSecurity, or an owning team, cost centre, or service tier.
Metadata is there so that reporting and automation can group projects the way your organisation is actually structured rather than the way the package registry sees it. Editing it requires the Manage projects permission.
API Keys
Section titled “API Keys”An API key binds a package install or a scanner upload to a project name and a workspace. It is what makes a request attributable and what selects the policy applied to it.
Generate keys under Settings -> API Keys, choosing an expiration of 30 days, 90 days, a year, or never.
- Generate a key per project or deployment target, so access and auditing map to real ownership. A single key shared across every pipeline collapses your traceability into one indistinguishable stream.
- Copy the key when it is created. It cannot be retrieved again afterwards. Store it in your normal secret-management system.
- Prefer an expiry for keys held by long-lived infrastructure, and treat the expiry warning as a scheduled rotation rather than an emergency.
- To rotate, create a new key with the same project name and retire the old one. Package activity history follows the project name, so rotating does not break continuity.
- Revoke immediately if a key is exposed or a machine is decommissioned.
Managing keys requires the Manage API keys permission. See Proxy Authentication for configuring each package manager with a key.
Members and Roles
Section titled “Members and Roles”Members are managed under Settings -> Members. Add a member using their verified email address, or their exact identity-provider subject where the provider does not supply a verified email claim. Membership shows as a pending invitation until their first successful sign-in, after which it links to their identity automatically.
ShieldedStack does not hold passwords. Authentication is your identity provider’s job; ShieldedStack decides what an authenticated person may do.
There are two tenant roles:
- Admin has access to every workspace in the tenant with all permissions. Keep this list short.
- User is granted access to specific workspaces, with permissions chosen per workspace. The same person can be an administrator of a development workspace and read-only in production.
A member with no permissions on a workspace still has read access to it. Permissions are what grant change.
| Permission | Allows |
|---|---|
| Manage workspaces | Create, rename, and configure workspaces |
| Manage projects | Edit project descriptions and metadata |
| Manage configuration | Change the Settings page: allow and deny list behaviour, block level, running mode, grace period, alert cooldown |
| Manage package policy | Add and edit package filters, and record or revoke vulnerability exceptions |
| Manage API keys | Generate and revoke API keys |
| Manage connectors | Configure notification channels |
| Triage alerts | Acknowledge alerts |
Two of these deserve deliberate handling. Manage configuration and Manage package policy together decide what the proxy blocks, which means they decide whether a vulnerable package can enter a build. Grant them to the people accountable for that outcome, and let everyone else read the same data and raise the finding.
A workable default for most teams: developers get Triage alerts so the queue actually gets worked, platform or security owns configuration and policy, and whoever runs the pipelines gets Manage API keys.