VenafiTLSProtect
Retrieves information about certificates stored in Venafi.
IT Services · CyberArk Certificate Manager Self-Hosted
Details
| ID | VenafiTLSProtect |
|---|---|
| Provider | CyberArk |
| Category | IT Services |
| From Version | 6.9.0 |
| Docker Image | demisto/python3:3.12.13.10116658 |
| Supported Modules | Agentix XSIAM |
README
Retrieves information about certificates stored in Venafi.
Configure CyberArk Certificate Manager on Cortex XSOAR
- Navigate to Settings > Integrations > Servers & Services.
- Search for CyberArk Certificate Manager.
-
Click Add instance to create and configure a new integration instance.
Parameter Required Server URL (e.g., https://192.168.0.1) True User Name True Password True Client ID True Trust any certificate (not secure) False Use system proxy settings False - Click Test to validate the URLs, token, and connection.
Commands
You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.
venafi-get-certificates
Gets Venafi certificates query. All dates are in 2016-11-12T00:00:00.0000000Z format. For additional field information, see: https://ao-tlspd.dev.ven-eco.com/aperture/help/Content/SDK/WebSDK/r-SDK-Certificates-search-attribute.htm and https://ao-tlspd.dev.ven-eco.com/aperture/help/Content/SDK/WebSDK/r-SDK-Certificates-search-status.htm
Base Command
venafi-get-certificates
Input
| Argument Name | Description | Required |
|---|---|---|
| CreatedOn | The date on which the certificated was created. Specify YYYY-MM-DD or the ISO 8601 format. | Optional |
| CreatedOnGreater | Find certificates created after this date. Specify YYYY-MM-DD or the ISO 8601 format. | Optional |
| CreatedOnLess | Find certificates created before this date. Specify YYYY-MM-DD or the ISO 8601 format. | Optional |
| Disabled | Include only certificates that are enabled 0 or disabled 1. | Optional |
| InError | Whether to include only certificates that are in an error state (1) or not in an error state (0). | Optional |
| ValidationState | Validation state. Possible values are: Blank, Success, Failure. | Optional |
| ManagementType | Management type. Possible values are: Unassigned, Monitoring, Enrollment, Provisioning. | Optional |
| Name | Name of the certificate object. | Optional |
| NetworkValidationDisabled | Whether to include only certificates with network validation disabled (1) or enabled (0). | Optional |
| ParentDn | The full path to the parent of the object in Trust Protection Platform (e.g., \VED\Policy\Engineering,\VED\Policy\HR). | Optional |
| ParentDnRecursive | The specific folder from which to retrieve certificates. (The subfolders will also be scanned.) Accepts a single value. | Optional |
| PendingWorkflow | Whether to include only certificates that are pending workflow resolution (have an outstanding workflow ticket). | Optional |
| Stage | Comma-separated list of stages in the certificate lifecycle. Will retrieve certificates at one or more of the stages. | Optional |
| StageGreater | Find certificates with a stage greater than the specified stage (does not include specified stage). | Optional |
| StageLess | Stage before which to retrieve certificates. | Optional |
| ValidationDisabled | Whether to include only certificates with validation disabled (1) or enabled (0). | Optional |
| C | Find certificates by Country attribute of Subject DN. | Optional |
| CN | Find certificates by Common name attribute of Subject DN. | Optional |
| Issuer | Find certificates by issuer. Use the CN ,O, L, S, and C values from the certificate request. Surround the complete value within double quotes (“). If a value already has double quotes, escape them with a second set of double quotes. For example, OU=”“(c) 2020 Entrust, Inc. - for authorized use only””. | Optional |
| KeyAlgorithm | Algorithm for the public key in the certificate (e.g., RSA, DSA). | Optional |
| KeySize | Comma-separated list of the bit size of the public key in the certificate (e.g., 2048). | Optional |
| KeySizeGreater | The size for which the public key size is greater than. | Optional |
| KeySizeLess | The size for which the public key size is less than. | Optional |
| L | Find certificates by Locality/City attribute of Subject Distinguished Name (SDN). | Optional |
| O | Find certificates by Organization attribute of Subject DN. | Optional |
| S | Find certificates by State/Province attribute of Subject DN. | Optional |
| Serial | Serial number of the certificate. | Optional |
| SignatureAlgorithm | The algorithm used to sign the certificate (e.g., SHA1RSA). | Optional |
| ValidFrom | Date on which the certificate was issued (e.g., 2015- 10-08T19:15:35.6431456Z or 2015-10-08). | Optional |
| ValidTo | Date on which the certificate expires (e.g., 2015-10- 08T19:15:35.6431456Z or 2015-10-08). | Optional |
| ValidToGreater | Date after which the certificates expire. | Optional |
| ValidToLess | Date before which the certificates expire. | Optional |
| Limit | The maximum number of certificates to return. Default value = 50. | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| Venafi.Certificate.CreatedOn | date | The exact date and time when the certificate object was created. |
| Venafi.Certificate.DN | string | The DN of the certificate. |
| Venafi.Certificate.Name | string | The name of the certificate. |
| Venafi.Certificate.ParentDN | string | The full path to the parent of the object in Trust Protection Platform. |
| Venafi.Certificate.SchemaClass | string | The class name of the certificate object. |
| Venafi.Certificate.ID | string | The certificate object GUID. |
| Venafi.Certificate.X509 | dictionary | Enrolled or issued certificate information: CN, Issuer, KeyAlgorithm, KeySize, SANS, Serial, Subject, Thumbprint, ValidFrom, ValidTo. |
venafi-get-certificate-details
Uses a certificate GUID to extract more details from the certificate store.
Base Command
venafi-get-certificate-details
Input
| Argument Name | Description | Required |
|---|---|---|
| guid | The ID of the certificate. Get certificates ID by running the command “venafi-get-certificates”. | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| Venafi.Certificate.ID | string | The certificate object GUID. |
| Venafi.Certificate.ParentDN | string | The full path to the parent of the object in Trust Protection Platform. |
| Venafi.Certificate.CreatedOn | date | The exact date and time when the Certificate object was created. |
| Venafi.Certificate.DN | string | The DN of the certificate. |
| Venafi.Certificate.Name | string | The name of the certificate. |
| Venafi.Certificate.SchemaClass | string | The class name of the certificate object. |
| Venafi.Certificate.Approver | string | An array of one or more users or groups who are certificate approvers. |
| Venafi.Certificate.CertificateAuthorityDN | string | The CA template that is required for certificate renewal. |
| Venafi.Certificate.Contact | string | An array of one or more users or groups who receive event notifications. The events notify people about certificate expiration and validation failures. |
| Venafi.Certificate.Description | string | Certificate description. |
| Venafi.Certificate.ManagedBy | string | Certificate manager. |
| Venafi.Certificate.ManagementType | string | The level of management that the Trust Protection Platform applies to the certificate. |
| Venafi.Certificate.CertificateDetails.AIAKeyIdentifier | string | Authority key identifier. |
| Venafi.Certificate.CertificateDetails.Issuer | string | The CN, O, L, S, and C values from the certificate request. |
| Venafi.Certificate.CertificateDetails.Serial | string | The unique serial number that the CA assigned to the certificate. |
| Venafi.Certificate.CertificateDetails.Subject | string | The CN, O, L, S, and C values from the certificate request. |
| Venafi.Certificate.CertificateDetails.Thumbprint | string | The SHA1 thumbprint hash of the certificate. |
| Venafi.Certificate.CertificateDetails.ValidFrom | string | Certificate validation start date. |
| Venafi.Certificate.CertificateDetails.ValidTo | string | Certificate validation end time. |
| Venafi.Certificate.CertificateDetails.AIACAIssuerURL | array | Available only when the certificate was issued by a well-configured CA. An array of Authority Information Access (AIA). Shows the CA issuer link and the CA’s certificate details. May also include Online Certificate Status Protocol (OCSP) information about revocation. |
| Venafi.Certificate.CertificateDetails.CN | string | The Common Name attribute of Subject Distinguished Name (DN). |
| Venafi.Certificate.CertificateDetails.EnhancedKeyUsage | string | The PKI Server Authentication object identifier (OID). |
| Venafi.Certificate.CertificateDetails.KeyAlgorithm | string | The algorithm for the public key. |
| Venafi.Certificate.CertificateDetails.KeySize | string | Only available for RSA certificates. The bit size of the public key. |
| Venafi.Certificate.CertificateDetails.KeyUsage | string | A list of Key Usage extension values that describe the purpose of the public key. |
| Venafi.Certificate.CertificateDetails.OU | string | An array of Organization Units or names. |
| Venafi.Certificate.CertificateDetails.PublicKeyHash | string | The public key hash string. Available only when the certificate has a private key. |
| Venafi.Certificate.CertificateDetails.SKIKeyIdentifier | string | The generated Subject Key Identifier (SKI). |
| Venafi.Certificate.CertificateDetails.SignatureAlgorithm | string | The signature algorithm for signing the certificate. |
| Venafi.Certificate.CertificateDetails.SignatureAlgorithmOID | string | The Signature Object ID for signing the certificate. |
| Venafi.Certificate.CertificateDetails.StoreAdded | string | The Date Time stamp when the private key was added to the store. |
| Venafi.Certificate.CertificateDetails.SubjectAltNameDNS | string | An array of Domain Name System (DNS) SANs. |
| Venafi.Certificate.CertificateDetails.SubjectAltNameEmail | string | An array of Email SANs. Based on RFC 822. |
| Venafi.Certificate.CertificateDetails.SubjectAltNameOtherNameUPN | string | An array of User Principal Name (UPN) SANs. |
| Venafi.Certificate.CertificateDetails.SubjectAltNameIPAddress | string | An array of IP address SANs. |
| Venafi.Certificate.CertificateDetails.SubjectAltNameURI | string | An array of Uniform Resource Indicator (URI) SANs. |
| Venafi.Certificate.CreatedBy | string | The object that initiated enrollment or provisioning changes. The default is Web SDK. |
| Venafi.Certificate.Origin | string | Filter by origin. |
| Venafi.Certificate.ProcessingDetails | dictionary | Absent when the certificate is not currently processing in the Trust Protection Platform lifecycle: InError, InProcess, Stage, Status, TicketDN. |
| Venafi.Certificate.RenewalDetails | dictionary | A list of certificate renewal information. |
| Venafi.Certificate.ValidationDetails | dictionary | A list of host identity information and the overall certificate validation state result. If no validation occurred, only the lastvalidationstateupdate field appears. All other validationdetails fields are absent. |
Configuration parameters
server— Server URL (e.g., https://192.168.0.1) (required)credentials— User Name (required)client_id— Client ID (required)insecure— Trust any certificate (not secure)proxy— Use system proxy settings
Commands (2)
-
venafi-get-certificate-detailsUses a certificate GUID to extract more details from the certificate store.
-
venafi-get-certificatesGets Venafi certificates query. All dates are in 2016-11-12T00:00:00.0000000Z format. For additional field information, see: https://ao-tlspd.dev.ven-eco.com/aperture/help/Content/SDK/WebSDK/r-SDK-Certificates-search-attribute.htm and https://ao-tlspd.dev.ven-eco.com/aperture/help/Content/SDK/WebSDK/r-SDK-Certificates-search-status.htm
import json import pytest from freezegun import freeze_time from VenafiV2 import Client MOCK_BASEURL = "https://mock.api.url.com" MOCK_CLIENT_ID = "mock_client_id" MOCK_CLIENT_PASSWORD = "mock_password" MOCK_USERNAME = "mock_username" def util_load_json(path): with open(path, encoding="utf-8") as f: return json.loads(f.read()) @pytest.fixture(autouse=True) @freeze_time("2024-04-25 00:00:00") def mock_client_with_valid_token(mocker) -> Client: """ Establish a connection to the client with a URL and user credentials. This client contains a valid token. Returns: Client: Connection to client. """ mocker.patch("VenafiV2.get_integration_context", return_value={"access_token": "access_token", "access_until": 1715032135}) mocker.patch("VenafiV2.get_current_time") return Client( base_url=MOCK_BASEURL, verify=False, username=MOCK_USERNAME, password=MOCK_CLIENT_PASSWORD, client_id=MOCK_CLIENT_ID, proxy=False, ) """*****TEST LOGIN****""" def test_login_first_time_token_creation(mocker): """ Given: An empty integration context When: Login is called for the first time Then: Create a new token and save it to the integration context """ mock_response = util_load_json("test_data/mock_response_login_first_time_token_creation.json") mocker.patch.object(Client, "_http_request", return_value=mock_response) mocker.patch("VenafiV2.get_integration_context", return_value={}) mocker.patch("VenafiV2.set_integration_context") mocker.patch("VenafiV2.get_current_time") client = Client( base_url=MOCK_BASEURL, verify=False, username=MOCK_USERNAME, password=MOCK_CLIENT_PASSWORD, client_id=MOCK_CLIENT_ID, proxy=False, ) assert client.token == "access_token" @freeze_time("2024-04-25 00:00:00") def test_login_with_valid_token(mock_client_with_valid_token): """ Given: A token in the integration context with a valid expiration time When: Login is called with a valid token Then: Fetch the token from the integration context and log in """ assert mock_client_with_valid_token.token == "access_token" @freeze_time("2024-04-25 00:00:00") def test_login_with_invalid_token_refresh_required(mocker): """ Given: A token in the integration context with an expired expiration time When: Login is called with an invalid token Then: Request a refresh token and save it to the integration context """ mocker.patch( "VenafiV2.get_integration_context", return_value={ "access_token": "access_token", "access_until": 1615032135, "refresh_token": "refresh_token", "refresh_until": 1745566543, }, ) mock_response = util_load_json("test_data/mock_response_login_without_valid_token.json") mocker.patch.object(Client, "_http_request", return_value=mock_response) mocker.patch("VenafiV2.set_integration_context") mocker.patch("VenafiV2.get_current_time") client = Client( base_url=MOCK_BASEURL, verify=False, username=MOCK_USERNAME, password=MOCK_CLIENT_PASSWORD, client_id=MOCK_CLIENT_ID, proxy=False, ) assert client.token == "access_token" @freeze_time("2024-04-25 00:00:00") def test_login_with_expired_access_and_refresh_tokens(mocker): """ Given: Both access and refresh tokens are expired in the integration context When: Login is called Then: Should create a new token using username/password """ mock_response = util_load_json("test_data/mock_response_login_first_time_token_creation.json") mocker.patch.object(Client, "_http_request", return_value=mock_response) mocker.patch( "VenafiV2.get_integration_context", return_value={ "access_token": "expired_access_token", "access_until": 1000000000, # expired "refresh_token": "expired_refresh_token", "refresh_until": 1000000000, # expired }, ) mocker.patch("VenafiV2.set_integration_context") mocker.patch("VenafiV2.get_current_time") client = Client( base_url=MOCK_BASEURL, verify=False, username=MOCK_USERNAME, password=MOCK_CLIENT_PASSWORD, client_id=MOCK_CLIENT_ID, proxy=False, ) assert client.token == "expired_access_token" def test_login_with_missing_tokens(mocker): """ Given: No tokens in the integration context When: Login is called Then: Should create a new token using username/password """ mock_response = util_load_json("test_data/mock_response_login_first_time_token_creation.json") mocker.patch.object(Client, "_http_request", return_value=mock_response) mocker.patch("VenafiV2.get_integration_context", return_value={}) mocker.patch("VenafiV2.set_integration_context") mocker.patch("VenafiV2.get_current_time") client = Client( base_url=MOCK_BASEURL, verify=False, username=MOCK_USERNAME, password=MOCK_CLIENT_PASSWORD, client_id=MOCK_CLIENT_ID, proxy=False, ) assert client.token == "access_token" def test_login_create_token_failure(mocker): """ Given: Token creation raises an exception When: Login is called Then: Exception should be propagated """ mocker.patch.object(Client, "_http_request", side_effect=Exception("Token creation failed")) mocker.patch("VenafiV2.get_integration_context", return_value={}) mocker.patch("VenafiV2.set_integration_context") mocker.patch("VenafiV2.get_current_time") with pytest.raises(Exception, match="Token creation failed"): Client( base_url=MOCK_BASEURL, verify=False, username=MOCK_USERNAME, password=MOCK_CLIENT_PASSWORD, client_id=MOCK_CLIENT_ID, proxy=False, ) @freeze_time("2024-04-25 00:00:00") def test_get_certificates_command(mocker, mock_client_with_valid_token): """ Given: Client details When: The "Get certificates" command is called Then: Retrieve the user's certificates """ from VenafiV2 import get_certificates_command raw_response = util_load_json("test_data/raw_certificates.json") mocker.patch.object(Client, "_http_request", return_value=raw_response) command_result = get_certificates_command(mock_client_with_valid_token, {}) certificates = command_result.outputs assert len(certificates) == 2 assert certificates == raw_response.get("Certificates", []) assert certificates[0].get("ID") == "first_guid" assert certificates[1].get("ID") == "second_guid" assert certificates[0].get("Guid") is None assert certificates[1].get("Guid") is None assert certificates[0].get("_links") is None @freeze_time("2024-04-25 00:00:00") def test_get_certificate_details_command(mocker, mock_client_with_valid_token): """ Given: Client details When: The "Get certificate details" command is called Then: Retrieve details of a specific certificate """ from VenafiV2 import get_certificate_details_command raw_response = util_load_json("test_data/raw_certificate_details.json") mocker.patch.object(Client, "_http_request", return_value=raw_response) command_result = get_certificate_details_command(mock_client_with_valid_token, {"guid": "guid"}) certificate_details = command_result.outputs assert certificate_details == raw_response assert certificate_details.get("ID") == "certificate_details_guid" assert certificate_details.get("Guid") is None assert certificate_details.get("Name") == "test.certificates.com" verbose_certificate_details = certificate_details.get("CertificateDetails") assert verbose_certificate_details is not None assert verbose_certificate_details.get("KeyAlgorithm") == "RSA" assert verbose_certificate_details.get("AIACAIssuerURL", [])[0] == "https://test.certificates.com"