VenafiTLSProtect

Retrieves information about certificates stored in Venafi.

IT Services · CyberArk Certificate Manager Self-Hosted

Details

IDVenafiTLSProtect
ProviderCyberArk
CategoryIT Services
From Version6.9.0
Docker Imagedemisto/python3:3.12.13.10116658
Supported ModulesAgentix XSIAM

README

Retrieves information about certificates stored in Venafi.

Configure CyberArk Certificate Manager on Cortex XSOAR

  1. Navigate to Settings > Integrations > Servers & Services.
  2. Search for CyberArk Certificate Manager.
  3. 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
  4. 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-details

    Uses a certificate GUID to extract more details from the certificate store.

  • 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

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"