Working with scanner versions

INFERENCE DEFEND

This article is meant for Inference Defend users.

ROLES AND PERMISSIONS

To complete the tasks described in this section, make sure you have the required permissions.

• Learn more about permissions in CalypsoAI

CalypsoAI provides several options for working with custom scanner versions.

• Learn how to create a custom scanner

You can do the following:

• Get a list of scanner versions
• Create a scanner version
• Publish a scanner version

Get a list of scanner versions

When working with scanners, you may find it useful to see all the versions created for a particular scanner.

To get the list of scanner versions:

1. Add your token and scanner ID values to the following sample:

   from calypsoai import CalypsoAI
   from calypsoai.datatypes import ProjectConfigScanner, UUID
   
   # Define the URL and token for CalypsoAI
   CALYPSOAI_URL="https://www.us1.calypsoai.app"
   CALYPSOAI_TOKEN="ADD-YOUR-TOKEN-HERE"
   
   # Initialize the CalypsoAI client
   cai = CalypsoAI(url=CALYPSOAI_URL, token=CALYPSOAI_TOKEN)
   
   # Get the list of all scanner versions
   versions = GetScannerVersionsResponse(versions=[version for version in cai.scanners.versions.iterate(scanner="ADD-YOUR-SCANNER-ID-HERE", onlyPublished=False)])
   
   # Print the response
   print(versions.model_dump_json(indent=2))

   PUBLISHED SCANNERS

   In the sample Python request, the onlyPublished attribute is set to False. To get a list containing only the published versions of the scanner, set onlyPublished to True.

2. Run the script.

3. Analyze the response.

   [{
       "createdAt": "2025-07-21T10:40:07.781554Z",
       "createdBy": "xxxxxxx",
       "description": "",
       "id": "01982c91-c665-7082-a8b8-b400bac9ec4d",
       "name": "v_2",
       "published": true
    }, {
       "createdAt": "2025-07-21T10:39:35.152053Z",
       "createdBy": "xxxxxxxx",
       "description": "",
       "id": "01982c91-46f0-7009-b409-286411c65035",
       "name": "v_1",
       "published": true
    }
   ]

Create a scanner version

A new scanner version is created each time you update a scanner.

In this scenario, we are going to create the second version of a custom keyword scanner, adding an additional keyword we want to include in the scan.

To create a scanner version:

1. Edit the following sample.

   from calypsoai import CalypsoAI
   from calypsoai.datatypes import KeywordScannerConfig, ScannerDirection,
   ScannerVersionInputModel
   
   # Define the URL and token for CalypsoAI
   CALYPSOAI_URL="https://www.us1.calypsoai.app"
   CALYPSOAI_TOKEN="ADD-YOUR-TOKEN-HERE"
   
   # Initialize the CalypsoAI client
   cai = CalypsoAI(url=CALYPSOAI_URL, token=CALYPSOAI_TOKEN)
   
   # Update the scanner version
   config = KeywordScannerConfig(words=["hello", "world", "newWord"], type="keyword")
   
   version = ScannerVersionInputModel(name="ADD-YOUR-VERSION-NAME-HERE", description="ADD-YOUR-VERSION-DESCRIPTION-HERE",
   published=False, push=False)
   
   response = cai.scanners.update(scanner = "ADD-YOUR-SCANNER-ID-HERE", name='ADD-YOUR-SCANNER-NAME-HERE',
   config=config, direction=ScannerDirection.BOTH, published=False)
   
   # Print the response
   print(response.model_dump_json(indent=2))

   • Add your token value.
   • In config, update your scanner's scan parameters, if required.
     In this scenario, we added the keyword newWord to the words list.
   • In version, do the following:

     SCANNER VERSIONS

     If you don't set a version when updating a custom scanner, the system creates a version for you and automatically assigns a version name, with the following additional configuration:

     • description left empty.
     • published and push set to False.
     • In name, provide a name for your new scanner version.
     • In description, provide a description for your new scanner version.
       This is an optional parameter. You can include it to add context and describe the changes made in each new scanner version.
     • In published, enter either True or False.
       If set to True, the scanner version is published and made available for use.
       The default value for this property is False.
     • In push, enter either True or False.
       If set to True, the scanner version is pushed to all projects in which the scanner is included, and automatically set as the active version. As a prerequisite, the scanner version can only be pushed if published is set to True.
       The default value for this property is False.
   • In response, do the following:
     • In scanner, provide the ID of the scanner you want to update.
     • In name, provide the name of the scanner you want to update.
     • In direction, define the direction of the scan.
       The direction property defines if the scan analyzes the request, the response, or both. You can choose one of the following three options:
       • REQUEST: Only the request (prompt) is scanned. This is the default selection.
       • RESPONSE: Only the LLM response is scanned.
       • BOTH: Both the request and response are scanned.
     • In published, enter either True or False.

       PUBLISHING SCANNER VERSIONS

       • If you don't set a version, or version is invalid, the publishing behavior of the scanner version depends on the value of the published property in response.
       • If version includes the published property, the publishing behavior of the scanner version depends on this value.
       • If the published property is included in both version and response, the publishing behavior of the scanner version depends on the value of the published property in version.

2. Run the script.

3. Analyze the response.

   {
       "createdAt": "2025-07-29T14:25:32.273974Z",
       "createdBy": null,
       "description": "ADD-YOUR-VERSION-DESCRIPTION-HERE",
       "id": "01985693-0471-70ed-9359-527a103f4793",
       "name": "ADD-YOUR-VERSION-NAME-HERE",
       "published": false
   }

Publish a scanner version

Publishing a scanner version makes it available for scanning prompts and scan requests, and for use in your projects and scanner packages.

To publish a scanner version:

1. Add your token, scanner ID, and version ID values to the following sample:

   from calypsoai import CalypsoAI
   
   # Define the URL and token for CalypsoAI
   CALYPSOAI_URL="https://www.us1.calypsoai.app"
   CALYPSOAI_TOKEN="ADD-YOUR-TOKEN-HERE"
   
   # Initialize the CalypsoAI client
   cai = CalypsoAI(url=CALYPSOAI_URL, token=CALYPSOAI_TOKEN)
   
   # Publish the scanner version
   cai.scanners.versions.publish(scanner="ADD-YOUR-SCANNER-ID-HERE", version="ADD-YOUR-VERSION-ID-HERE", push=False)

   PUSH TO PROJECTS

   In the sample Python request, the push attribute is set to False. To push the scanner version to all projects in which the scanner is included, and automatically set the version as the active version, set push to True.

2. Run the script.
   If the request is successful, you receive the None response.

   THE NONE RESPONSE

   Confirm the scanner version is published by getting the list of scanner versions and checking the published attribute.

   • Learn more about the None response