API Security CLI Jobs

Panoptica enables you to shift left your API security, by proactively scanning for risks in the CI/CD stage. You can perform the following pre-production actions via CLI:

• Run a spec analysis job, by providing an OpenAPI specification
• Run a 3rd party API scoring job, by providing the URL to a 3rd party API
• Run a fuzzing job on an API endpoint that is reachable from Panoptica's API Security Controller.

See API Security CLI for instructions on downloading the code and generating the keys.

📘

MacOS Security

If you are using MacOS, execution of the CLI may be blocked for security reasons.
If so, go to System Preferences --> Privacy & Security to permit using the binary.

Once the CLI is downloaded, relocate it to the Download folder in your terminal, and change the permission, if you have not already done so.

mv ${HOME}/Downloads/apisec_cli ${PWD}  
chmod u+x apisec_cli

Running apisec_cli with various global options, command options, and arguments, you can configure authentication, check on your controller, and run and manage various jobs.

NAME:
   apisec_cli apisec-job - CI/CD tool

USAGE:
   apisec_cli apisec-job command [command options] [arguments...]

DESCRIPTION:
   Manage APISEC controllers and jobs

COMMANDS:
   list-controllers  Get a list of controllers
   help, h           Shows a list of commands or help for one command
   Manage jobs:
     get     Get a job's details
     list    List all jobs
     delete  Cancel a job
   Start jobs:
     start-fuzzing                  Deploy a fuzzing job
     start-third-party-api-scoring  Deploy a third party API job
     start-oas-scoring              Deploy an Open API Specification (OAS) scoring job

OPTIONS:
   Authentication:

   --access-key value  Specify the Panoptica CLI access key, or set the environment variable (Required) [$PANOPTICA_CLI_ACCESS_KEY]
   --secret-key value  Specify the Panoptica CLI secret key, or set the environment variable (Required) [$PANOPTICA_CLI_SECRET_KEY]

   Output:

   --json        Format output in JSON (default: false)
   --no-headers  Do not display the headers (default: false)

Configure the credentials

Once downloaded, the first step is authentication. Run the following commands to set the Secret Key and Access Key, using the values you downloaded from the API Security CLI tab in the Panoptica console.

export PANOPTICA_CLI_SECRET_KEY=<SECRET_KEY>
export PANOPTICA_CLI_ACCESS_KEY=<ACCESS_KEY>

If you prefer, you can save those commands in a file named cicd.api.keys, and call it with a source command.

Test your credentials by retrieving the controller ID, as follows:

./apisec_cli apisec-job list-controllers

The output should be similar to:

ID                                    NAME               
fea53415-e0c5-4db3-97ed-333736b5cd60  your-cluster  

Spec analysis job

This function analyzes OpenAPI Specification (OAS) that you provide for security issues.

Submit an OAS scoring job as follows. This also captures the JOB_ID as an environment variable.

Text

./apisec_cli apisec-job start-oas-scoring openapi/carts.json 2>&1 | tee output.txt

# Copy job id string into env var
export JOB_ID=$(cat output.txt | cut -d\" -f2)

The output should be similar to:

Created scoring job with id "3ca74f2f-a5a7-4d14-a200-efd6854092b8"

You can check on the job status using the poll option, as follows:

./apisec_cli apisec-job get --poll ${JOB_ID}

For example:

ID                                    JOBTYPE        STATUS     CREATED AT                            UPDATED AT                           
3ca74f2f-a5a7-4d14-a200-efd6854092b8  OasScoringJob  Completed  2024-01-11 11:39:12.389813 +0000 UTC  2024-01-11 11:39:12.479059 +0000 UTC  

View a summary of the findings as follows:

./apisec_cli apisec-job get --summary ${JOB_ID}

The output shows the list of findings and their severity, for example:

ID                                    SEVERITY  CATEGORIES         FINDING TYPE ID  SOURCE       
b047c477-dc62-4819-8850-d23861f6d588  info      api-specification  FBP010           oas-analyzer  
53e3be2f-fe09-49ae-ad11-11ff562992a3  info      api-specification  FST004           oas-analyzer  
75727e5b-cdb2-4c13-8d87-41d6165ba9a5  info      api-specification  FST004           oas-analyzer  
2e21d5f6-b366-463e-9e18-a24c9edd07e9  high      api-specification  TDT001           oas-analyzer  
4f3c1859-0d9a-43ae-95f6-dfed5b243957  high      api-specification  TDT001           oas-analyzer  
62204aa9-9443-4fd6-a1ae-0742dadc81a8  high      api-specification  TDT001           oas-analyzer  
be7ee97c-da28-40b8-b856-317b21d76480  high      api-specification  TDT001           oas-analyzer  
b3730708-abfb-4728-8353-f3806fd312dd  high      api-specification  TDT001           oas-analyzer  
cdb2a9eb-89ba-419e-bb82-7e6040c12fa3  high      api-specification  TDT001           oas-analyzer  
43d6c0d1-773c-44a3-9556-8ec946468b5a  medium    api-specification  TDT007           oas-analyzer  
6d5adf0b-8f9c-4ec2-8847-be02b42969b0  medium    api-specification  TDT007           oas-analyzer  
7ff50596-7bcb-4899-bd7a-1e01293b81c7  medium    api-specification  TDT007           oas-analyzer  

Get JSON output of the findings, which provides more details than the summary report above.
Note that the order of the arguments matters.

./apisec_cli apisec-job --json get --summary ${JOB_ID}

The output should be similar to:

{"createdAt":"2024-01-11T11:20:18.600099Z","id":"4d2a9201-ab84-4c2e-98aa-9960a009dc58","items":[{"additionalInfo":{"specPath":"#/components/schemas/ApplicationDeploymentUpdate/properties/configuration/additionalProperties"},"categories":["api-specification"],"createdAt":"2024-01-11T11:20:28.328951Z","description":"The spec defines a value for a property that is not compatible with the property type.  This means that the type or the values are not correct. In the former case, validation performed by server or client might not be accurate, potentially posing security issues with malformed data.","detailedDescription":"The spec defines a value for a property that is not compatible with the property type.  This means that the type or the values are not correct. In the former case, validation performed by server or client might not be accurate, potentially posing security issues with malformed data.","findingTypeId":"FBP010","id":"b047c477-dc62-4819-8850-d23861f6d588","severity":"info","source":"oas-analyzer"},{"additionalInfo":{"specPath":"#/components/schemas/SiteSettings/properties/observability"},"categories":["api-specification"],
...

3rd party API scoring job

This function enables you to run a scoring job on a 3rd party API based on a URL that you provide.

The following example submits a scoring job using the public API of the US National Weather Service. This also captures the JOB_ID as an environment variable.

./apisec_cli apisec-job start-third-party-api-scoring --poll --url <https://api.weather.gov> 2>&1 | tee output.txt

# Copy job id string into env var
export JOB_ID=$(cat output.txt | cut -d\" -f2)

You can fetch summary results of this job using the JOB_ID as follows:

./apisec_cli apisec-job get --summary ${JOB_ID}

Get JSON output of the findings, which provides more details than the summary report above.

./apisec_cli apisec-job --json get --summary ${JOB_ID}

Note that the order of the arguments matters.

API Fuzz testing

Fuzz testing is used to evaluate APIs for security issues, by providing invalid, unexpected, or random data as inputs. To run a fuzz test on your APIs, you must have the Panoptica API Security controller deployed in a Kubernetes cluster, with network access to your APIs, as the fuzzing job will use our controller to fuzz an API in your cluster.

There are three levels of fuzzing depth available, which you set in the command line:

• quick - these scans take about 5 minutes
• default - these tests take about 15 minutes
• deep - these tests take about 30 minutes

If you have not already done so, run the following commands to set the Secret Key and Access Key, using the values you downloaded from the API Security CLI tab in the Panoptica console.

export PANOPTICA_CLI_SECRET_KEY=<SECRET_KEY>
export PANOPTICA_CLI_ACCESS_KEY=<ACCESS_KEY>

Then retrieve the controller ID, as follows:

./apisec_cli apisec-job list-controllers

It's also useful to save the controller ID as an environment variable, as follows:

export CONTROLLER_ID=<CONTROLLER ID>

Now you're ready to run the fuzzing job. The following example submits a Quick fuzzing job on your API. The maximum severity allowed for this job to be marked as compliant is Info, which is the lowest level. The spec file for the API tested is spec-file.json.

./apisec_cli apisec-job start-fuzzing --url <URL of your API> --fuzzing-depth Quick --controller-id $CONTROLLER_ID --max-severity-allowed Info spec-file.json

Once the job is created, you will receive a JOB_ID. You can see a list of all the jobs − and check on their status − using the list command:

./apisec_cli apisec-job list

Finally, retrieve the results of the fuzzing job using a get command, as follows:

./apisec_cli apisec-job --json get --summary '\<JOB_ID>' | jq

Use cases for pre-production scanning and scoring

By integrating the Panoptica API Security CLI in your CI/CD/testing pipeline, you can:

• test all specs in the repository whenever CI is executed, and alert or block any job where the resulting findings are not compliant.
• analyze all known 3rd party API in use when CI is executed, and alert or block any job where the resulting findings are not compliant.
• fuzz known internal APIs in staging CD or as part of the system tests, and alert or block any job where the resulting findings are not compliant.

The results of the pre-production jobs run via CLI (spec analysis, 3rd party scoring, and fuzzing) do not appear in the API Asset Catalog, and they do not contribute to the security findings in the Panoptica console. The results remain available in the database for one week, after which they are deleted.