Package org.zaproxy.clientapi.core

Class ClientApi

  • public class ClientApi
extends java.lang.Object

    • Constructor Detail

      • ClientApi

        public ClientApi​(java.lang.String zapAddress,
                 int zapPort)

      • ClientApi

        public ClientApi​(java.lang.String zapAddress,
                 int zapPort,
                 java.lang.String apiKey)
        Constructs a ClientApi with the given ZAP address/port and with the given API key, to be sent with all API requests.
        Parameters:
        zapAddress - ZAP's address
        zapPort - ZAP's listening port
        apiKey - the ZAP API key, might be null or empty in which case is not used/sent.
        Since:
        1.1.0

      • ClientApi

        public ClientApi​(java.lang.String zapAddress,
                 int zapPort,
                 boolean debug)

      • ClientApi

        public ClientApi​(java.lang.String zapAddress,
                 int zapPort,
                 java.lang.String apiKey,
                 boolean debug)
        Constructs a ClientApi with the given ZAP address/port and with the given API key, to be sent with all API requests. Also, sets whether or not client API debug information should be written to the debug stream (by default the standard output stream).
        Parameters:
        zapAddress - ZAP's address
        zapPort - ZAP's listening port
        apiKey - the ZAP API key, might be null or empty in which case is not used/sent.
        debug - true if debug information should be written to debug stream, false otherwise.
        Since:
        1.1.0

    • Method Detail

      • setDebugStream

        public void setDebugStream​(java.io.PrintStream debugStream)

      • callApi

        public ApiResponse callApi​(java.lang.String requestMethod,
                           java.lang.String component,
                           java.lang.String type,
                           java.lang.String method,
                           java.util.Map<java.lang.String,​java.lang.String> params)
                    throws ClientApiException
        Throws:
        ClientApiException

      • callApiOther

        public byte[] callApiOther​(java.lang.String component,
                           java.lang.String type,
                           java.lang.String method,
                           java.util.Map<java.lang.String,​java.lang.String> params)
                    throws ClientApiException
        Throws:
        ClientApiException

      • callApiOther

        public byte[] callApiOther​(java.lang.String requestMethod,
                           java.lang.String component,
                           java.lang.String type,
                           java.lang.String method,
                           java.util.Map<java.lang.String,​java.lang.String> params)
                    throws ClientApiException
        Throws:
        ClientApiException

      • addExcludeFromContext

        @Deprecated
public void addExcludeFromContext​(java.lang.String apiKey,
                                  java.lang.String contextName,
                                  java.lang.String regex)
                           throws java.lang.Exception
        Deprecated.
        (1.1.0) Use Context.excludeFromContext(String, String) instead.
        Adds the given regular expression to the exclusion list of the given context.
        Parameters:
        apiKey - the API key, might be null.
        contextName - the name of the context.
        regex - the regular expression to add.
        Throws:
        java.lang.Exception - if an error occurred while calling the API.
        See Also:
        context

      • addIncludeInContext

        @Deprecated
public void addIncludeInContext​(java.lang.String apiKey,
                                java.lang.String contextName,
                                java.lang.String regex)
                         throws java.lang.Exception
        Deprecated.
        (1.1.0) Use Context.includeInContext(String, String) instead.
        Adds the given regular expression to the inclusion list of the given context.
        Parameters:
        apiKey - the API key, might be null.
        contextName - the name of the context.
        regex - the regular expression to add.
        Throws:
        java.lang.Exception - if an error occurred while calling the API.
        See Also:
        context

      • includeOneMatchingNodeInContext

        @Deprecated
public void includeOneMatchingNodeInContext​(java.lang.String apiKey,
                                            java.lang.String contextName,
                                            java.lang.String regex)
                                     throws java.lang.Exception
        Deprecated.
        (1.1.0) Use includeOneMatchingNodeInContext(String, String) instead.
        Includes just one of the nodes that match the given regular expression in the context with the given name.

        Nodes that do not match the regular expression are excluded.

        Parameters:
        apiKey - the API key, might be null.
        contextName - the name of the context.
        regex - the regular expression to match the node/URL.
        Throws:
        java.lang.Exception - if an error occurred while calling the API.

      • includeOneMatchingNodeInContext

        public void includeOneMatchingNodeInContext​(java.lang.String contextName,
                                            java.lang.String regex)
                                     throws java.lang.Exception
        Includes just one of the nodes that match the given regular expression in the context with the given name.

        Nodes that do not match the regular expression are excluded.

        Parameters:
        contextName - the name of the context.
        regex - the regular expression to match the node/URL.
        Throws:
        java.lang.Exception - if an error occurred while calling the API.

      • activeScanSiteInScope

        @Deprecated
public void activeScanSiteInScope​(java.lang.String apiKey,
                                  java.lang.String url)
                           throws java.lang.Exception
        Deprecated.
        (1.1.0) Use activeScanSiteInScope(String) instead, the API key should be set using one of the ClientApi constructors.
        Active scans the given site, that's in scope.

        The method returns only after the scan has finished.

        Parameters:
        apiKey - the API key, might be null.
        url - the site to scan
        Throws:
        java.lang.Exception - if an error occurred while calling the API.

      • activeScanSiteInScope

        public void activeScanSiteInScope​(java.lang.String url)
                           throws java.lang.Exception
        Active scans the given site, that's in scope.

        The method returns only after the scan has finished.

        Parameters:
        url - the site to scan
        Throws:
        java.lang.Exception - if an error occurred while calling the API.
        Since:
        1.1.0

      • waitForSuccessfulConnectionToZap

        public void waitForSuccessfulConnectionToZap​(int timeoutInSeconds)
                                      throws ClientApiException
        Convenience method to wait for ZAP to be ready to receive API calls, when started programmatically.

        It attempts to establish a connection to ZAP's proxy, in the given time, throwing an exception if the connection is not successful. The connection attempts might be polled in one second interval.

        Parameters:
        timeoutInSeconds - the (maximum) number of seconds to wait for ZAP to start
        Throws:
        ClientApiException - if the timeout was reached or if the thread was interrupted while waiting
        See Also:
        waitForSuccessfulConnectionToZap(int, int)

      • waitForSuccessfulConnectionToZap

        public void waitForSuccessfulConnectionToZap​(int timeoutInSeconds,
                                             int pollingIntervalInMs)
                                      throws ClientApiException
        Convenience method to wait for ZAP to be ready to receive API calls, when started programmatically.

        It attempts to establish a connection to ZAP's proxy, in the given time, throwing an exception if the connection is not successful. The connection attempts are done with the given polling interval.

        Parameters:
        timeoutInSeconds - the (maximum) number of seconds to wait for ZAP to start
        pollingIntervalInMs - the interval, in milliseconds, for connection polling
        Throws:
        ClientApiException - if the timeout was reached or if the thread was interrupted while waiting.
        java.lang.IllegalArgumentException - if the interval for connection polling is negative.
        See Also:
        waitForSuccessfulConnectionToZap(int)