Skip to Content
SaaS

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:

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_TOKEN

When 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/api

Connection options

OptionEnvironment variableDescription
--tokenCS_TOKENCodesphere API token for authentication
--apiCS_APIURL of the Codesphere API. Defaults to https://cloud.codesphere.com/api
--orgCS_ORG_IDRestrict the scan to one organization ID
--resource-group, -GCS_RESOURCE_GROUP_IDRestrict the scan to one resource group ID
--discoverWhat 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_TOKEN
cnspec> 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_TOKEN

To scan a single resource group:

cnspec scan codesphere --token YOUR_TOKEN --resource-group RESOURCE_GROUP_ID

When 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:

TargetAssets
resource-groupsOne asset per resource group
workspacesOne asset per workspace
organizationsOne asset per organization, for membership checks
auto (default)Resource groups and workspaces
allResource groups, workspaces, and organizations

To include organizations in a scan:

cnspec scan codesphere --token YOUR_TOKEN --discover all

Asset 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_TOKEN

List 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: true

The same check works for organizations when the token's owner is an organization admin:

cnspec> codesphere.organizations.all(members.none(pending == true))
[ok] value: true

Review 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: true

To 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: true

Ensure workspaces don't build from public repositories

cnspec> codesphere.workspaces.where(gitUrl != null && gitUrl != "").all(isPrivateRepo == true)
[ok] value: true

Ensure 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: true

Ensure no workspace uses a deprecated plan

cnspec> codesphere.workspaces.where(workspacePlan != null).all(workspacePlan.deprecated == false)
[ok] value: true

Ensure every custom domain is verified and has a certificate

cnspec> codesphere.resourceGroups.all(customDomains.all(verified == true && certificateIssued == true))
[ok] value: true

To 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: true

Troubleshooting

  • Every field fails with a 401 error: The token is invalid or expired, or it belongs to a different installation than the one --api points at.
  • The members field of an organization fails with a 403 error: Listing organization members requires organization admin rights. The rest of the scan is unaffected.

Learn more

Last updated on

On this page