Secure Codesphere with cnspec
Scan Codesphere organizations, resource groups, and workspaces against security and compliance best practices with cnspec.
Scan your Codesphere installation to find security risks before they become incidents. cnspec evaluates who belongs to your organizations and resource groups, how workspaces and custom domains are exposed, where workspace code comes from, whether workspaces run on supported base images and plans, and more. It works with both the Codesphere cloud and Codesphere Private Cloud installations.
If you're new to cnspec, start with the Quickstart. For an overview of every SaaS service cnspec can scan, see the SaaS scanning overview.
Prerequisites
To scan Codesphere with cnspec, you must have:
- cnspec installed on your workstation
- A Codesphere account on the Codesphere cloud or on a Private Cloud installation
- A Codesphere API token
Authenticate
cnspec connects to Codesphere using an API token. Create one in the user settings of your Codesphere installation and copy the value.
A scan sees what the token's owner can see. To audit everything, use a token that belongs to a user who is an admin of the resource groups and organizations you want to scan. A resource group the token's owner isn't a member of, and doesn't administer through its organization, is left out of the scan. Listing organization members requires organization admin rights.
You can pass the token on the command line with --token, or export it once and reuse it across commands:
export CS_TOKEN=YOUR_TOKENWhen CS_TOKEN is set, you can omit the --token flag from the commands below. cnspec reads the same environment variables as the Codesphere cs CLI, so if you already use the CLI, cnspec picks up your settings.
Private Cloud installations
By default cnspec connects to the Codesphere cloud at https://cloud.codesphere.com/api. To scan a Private Cloud installation, pass its API URL with --api or set CS_API:
cnspec scan codesphere --token YOUR_TOKEN --api https://codesphere.example.com/apiConnection options
| Option | Environment variable | Description |
|---|---|---|
--token | CS_TOKEN | Codesphere API token for authentication |
--api | CS_API | URL of the Codesphere API. Defaults to https://cloud.codesphere.com/api |
--org | CS_ORG_ID | Restrict the scan to one organization ID |
--resource-group, -G | CS_RESOURCE_GROUP_ID | Restrict the scan to one resource group ID |
--discover | What to discover: auto (default), all, organizations, resource-groups, workspaces |
Verify with a quick Codesphere check
Confirm that cnspec can reach your Codesphere installation by opening a cnspec shell:
cnspec shell codesphere --token YOUR_TOKENcnspec> codesphere.resourceGroups { name }If cnspec connects and lists your resource groups, you're ready to scan. If a resource group you expected is missing, the token's owner isn't a member of it or an admin of its organization.
Scan Codesphere
cnspec scan codesphere --token YOUR_TOKENTo scan a single resource group:
cnspec scan codesphere --token YOUR_TOKEN --resource-group RESOURCE_GROUP_IDWhen a scan completes, cnspec prints a summary of all the checks it ran, grouped by policy, along with a risk score from 0 (no risk) to 100 (highest risk). Failed checks include remediation guidance to help you fix issues. To learn more about reading scan results, read Understand cnspec Results.
Choose what to discover
The installation itself is always scanned as one asset, which covers the catalog of data centers, workspace plans, and base images, along with the SSH keys of the token's owner. Discovery adds more assets:
| Target | Assets |
|---|---|
resource-groups | One asset per resource group |
workspaces | One asset per workspace |
organizations | One asset per organization, for membership checks |
auto (default) | Resource groups and workspaces |
all | Resource groups, workspaces, and organizations |
To include organizations in a scan:
cnspec scan codesphere --token YOUR_TOKEN --discover allAsset identity includes the API host, because resource group and workspace IDs are unique only within one installation. Scanning the Codesphere cloud and a Private Cloud installation never produces colliding assets.
Write your own policies
Mondoo doesn't yet ship an out-of-the-box Codesphere policy, so use the checks below as a starting point and create your own policies to meet your specific requirements.
Explore and test checks interactively
Open a cnspec shell to discover resources and try out checks:
cnspec shell codesphere --token YOUR_TOKENList organizations and their members
cnspec> codesphere.organizations { name members { email role pending } }List resource groups and their members
Resource groups were called teams in earlier versions of Codesphere:
cnspec> codesphere.resourceGroups { name organization.name members { email role pending } }List workspaces
cnspec> codesphere.workspaces { name resourceGroup.name restricted devDomain replicas }Inspect where a workspace's code comes from
cnspec> codesphere.workspaces { name gitUrl initialBranch isPrivateRepo }List custom domains and the workspaces they route to
cnspec> codesphere.resourceGroups { name customDomains { name verified certificateIssued connections { path workspaces { name } } } }Review the installation catalog
cnspec> codesphere.baseImages { id name supportedUntil }
cnspec> codesphere.workspacePlans { title deprecated cpu ramBytes }
cnspec> codesphere.dataCenters { name city countryCode }Example security checks
Ensure no invitation stays outstanding
cnspec> codesphere.resourceGroups.all(members.none(pending == true))
[ok] value: trueThe same check works for organizations when the token's owner is an organization admin:
cnspec> codesphere.organizations.all(members.none(pending == true))
[ok] value: trueReview who administers each resource group
cnspec> codesphere.resourceGroups { name members.where(role == "admin") { email } }Ensure access to every workspace is restricted
cnspec> codesphere.workspaces.all(restricted == true)
[ok] value: trueTo list the workspaces that anyone can reach on their dev domain:
cnspec> codesphere.workspaces.where(restricted == false) { name devDomain resourceGroup.name }Ensure no workspace embeds credentials in its git URL
cnspec replaces credentials embedded in a repository URL with xxxxx, so a token in the URL is detected without being exposed in scan results:
cnspec> codesphere.workspaces.none(gitUrl.contains("xxxxx@"))
[ok] value: trueEnsure workspaces don't build from public repositories
cnspec> codesphere.workspaces.where(gitUrl != null && gitUrl != "").all(isPrivateRepo == true)
[ok] value: trueEnsure every workspace runs on a supported base image
A workspace on the default image reports a null baseImage, so filter those out before comparing support dates:
cnspec> codesphere.workspaces.where(baseImage != null).all(baseImage.supportedUntil > time.now)
[ok] value: trueEnsure no workspace uses a deprecated plan
cnspec> codesphere.workspaces.where(workspacePlan != null).all(workspacePlan.deprecated == false)
[ok] value: trueEnsure every custom domain is verified and has a certificate
cnspec> codesphere.resourceGroups.all(customDomains.all(verified == true && certificateIssued == true))
[ok] value: trueTo see why a domain failed:
cnspec> codesphere.resourceGroups { name customDomains.where(verified == false || certificateIssued == false) { name verificationReason certificateReason } }Ensure persistent logs are enabled on every workspace
cnspec> codesphere.workspaces.all(persistentLogs == true)
[ok] value: trueTroubleshooting
- Every field fails with a 401 error: The token is invalid or expired, or it belongs to a different installation than the one
--apipoints at. - The
membersfield of an organization fails with a 403 error: Listing organization members requires organization admin rights. The rest of the scan is unaffected.
Learn more
- Codesphere Resource Pack Reference: every Codesphere resource and field cnspec can query
- Write Effective MQL: guide to authoring checks and queries
Last updated on