Topic
IC4NOTICE: developerWorks Community will be offline May 29-30, 2015 while we upgrade to the latest version of IBM Connections. For more information, read our upgrade FAQ.
1 reply Latest Post - ‏2014-06-05T19:36:10Z by Jonathan.Pechta (IBM)
Jonathan.Pechta (IBM)
22 Posts
ACCEPTED ANSWER

Pinned topic QRadar REST API - Frequently Asked Questions

‏2014-05-09T19:50:37Z |
  1. What is the purpose of the API forum?

    The purpose of this forum is intended for customers to exchange ideas, start discussions, or ask questions of developers and support representatives.  We appreciate all feedback about the API and will take comments listed here as advice to help improve APIs and access to data going forward. As always, it is beneficial to also raise a Request for Enhancement. This process associates the feature request to your customer information, which allows us to reach out to you in case we would like to discuss your suggestions further.

    How to open a Request for Enhancement (RFE) for QRadar:
      1. Click the following link to go to the QRadar SIEM RFE page: https://ibm.biz/BdRPx5
      2. Log in to the support portal page.
      3. Click the Submit tab and fill in the required information.

     
  2. What QRadar software releases support APIs?

    Any QRadar Console that is installed with QRadar 7.2.1 (7.2.1. or above can use features in the REST API.

    New features are added to the QRadar REST API during core software updates, for example, QRadar 7.2.1 or 7.2.2. As we develop and add features to the QRadar REST API, your QRadar version might not be able to leverage a new feature without a software upgrade. As new versions are released, we will update this FAQ to list new capabilities and post new sample code to assist customers with using new features.

     
  3. What are the API differences between the API features in QRadar versions?

    API Name 7.2.1 7.2.2 7.2.3 Description
    /ariel N/A Available Available The ariel API allows administrators to query event and flow databases, searches, create searches, search for IDs, and return search results.
    /auth Available Available Available The authorization API allows administrators to log out and invalidate the current session.
    /help Available Available Available Returns a list of API capabilities.
    /referencedata Available Available Available This API allows administrators to view and managed reference data collections within QRadar.
    /qvm Available Available Available The QRadar Vulnerability Manager API allows administrators to get assets, vulnerabilities, networks, open services, networks, filters, or post remediation tickets. A license for QRadar Vulnerability Manager is required to use this API.
    /scanner Available Available Available The scanner API allows administrators to view, create, or remotely launch a scan related to a scan profile. A license for QRadar Vulnerability Manager is required to use this API.
    /siem N/A N/A Available The siem API allows users or administrators to get offenses, closing reasons, notes, and offense IDs from the Console appliance.
    /asset_model N/A N/A Available The asset model API allows users or administrators to get assets, asset properties, lists of saved searches, and update asset IDs.

     
  4. What technology is used in the API and where do I find for information?

    IBM maintains a "Learn about" page for RESTful Web Services. A number of articles can be found at the following URL: http://www.ibm.com/developerworks/topics/restful%20web%20services
     
  5. How do I access to the REST API from my Console?

    The REST API is available from any browser that can access the QRadar Console. For example, https://ConsoleIPaddress/restapi/doc/.
    The REST API prompts the requestor to authenticate. An Admin Use Role is required to access the QRadar API.

    Note: In the 7.2.3 API version, a hosts file allows a shortened URL to access the API: https://ConsoleIPaddress/api_doc.
     
  6. What do the provisional, experimental, and stable tags listed for each API indicate?

    - Provisional/Experimental: Indicates that these API fields are subject to arbitrary change or removal without any notice.
    - Stable: Indicates that these API fields are stable and that they have been validated before release and are supported.
     
  7. Where can I find code samples?

    A set of sample scripts have been created for customers who want to leverage the QRadar API. These samples are provided for educational purposes. Samples follow the IBM developerWorks download terms of use: https://www.ibm.com/developerworks/community/terms/download/.

    Link to the forum post containing the QRadar API code samples: https://www.ibm.com/developerworks/community/forums/html/topic?id=19027124-50dc-4114-a3bf-57b927639f71
     
  8. What are the requirements to run the code samples?

    API code sample version Requirements
    Samples-7.2.1.zip
    • QRadar 7.2.1 (any patch level)
    • Python 3.3
    Samples-7.2.2.zip
    • QRadar 7.2.2 (any patch level)
    • Python 3.3
    Samples-7.2.3.zip
    • QRadar 7.2.3 (any patch level)
    • Python 3.3

    Note: Samples are now added to a GitHub repository. Users can see the following post for the URLs to download API code examples: https://www.ibm.com/developerworks/community/forums/html/topic?id=19027124-50dc-4114-a3bf-57b927639f71&ps=25
     
  9. Do you provide bindings for X-language?
    No, the QRadar REST API does not support any bindings for X-language.
     
  10. I am making a POST request to the API, but am receiving 404 errors,  "HTTP method [GET] is not supported by the endpoint at the given relative path (<PATH REQUESTED>) "

    This issue occurs with the 7.2.1 APIs when you follow the HTTP redirects automatically and the first request you are making is a POST request. Please note that the authentication process was changed in 7.2.2 for the APIs.  The "01_Authentication" code sample  for your version of QRadar (see FAQ #7) has more details about the authentication process.

    There are a couple things you can do to resolve this issue:

    A. Continue to follow the HTTP redirects, do the same steps as you outlined in your post, and then send another POST request to the bulkLoad URI supplying the JSESSIONID and SEC cookies in the request.

    B. You can send an initial GET request (to one of the API endpoints that supports GET) in order to authenticate for the API. In this instance, following the redirect will not produce the issue that you are experiencing and you can send your POST request to the bulkLoad URI supplying the JSESSIONID and SEC cookies.

    C. You can adjust your client code to turn off following HTTP redirects, which would allow you to receive the HTTP 302 Found response indicating you are authenticated. Then you can send  your POST request to https://logserver.local/restapi/api/referencedata/sets/bulkLoad including the JSESSIONID and SEC cookies.
     
  11. What do I do if I find a defect in the API?

    Any defects discovered with the QRadar REST API can be logged with QRadar Customer Support.

    How do I open a support ticket?
    1.    You can use this link to go to the QRadar SIEM support portal.
    2.    Under Tools and Resources, click Open a new service request - sign in.
    3.    Open your ticket and a QRadar support representative will contact you.
     
  12. What do I do if I have a question or get stuck?

    If you have a QRadar API question, you can use these forums. QRadar Customer Support representatives and QRadar software developers monitor these forums to assist users with issues and general questions. If you have a question, you can start a new topic in the API forum to ask your question.
     
  13. My QRadar Console is not installed with QRadar 7.2.1 or QRadar 7.2.2 is there a way to look at the API if I do not have these versions installed?

    Yes, at the bottom of this post we will attach two PDFs with the following content:
    -   The first PDF will contain screen captures from the QRadar 7.2.1 API.
    -   The second PDF contains screen captures from the QRadar 7.2.2 API.

    These PDFs display the in-product API user interface. The API user interface allows administrators to view descriptions and capabilities of the QRadar API. This document also contains interactive fields where administrators can try different values for GET, POST, or DELETE commands to see how the HTTP request should be formatted and to see success or error responses. 
     
  14. Is there updated API documentation?

    Yes, a new /offense endpoint was added in QRadar 7.2.3, along with other features. A change list is posted here: https://www.ibm.com/developerworks/community/forums/html/topic?id=3b20ef19-7a0b-4fb0-b095-89732b4a286f&ps=25.
  15. Will this FAQ be updated?
    Yes, we plan to update this FAQ for the following reasons:

    1. When new capabilities are released with QRadar updates, this FAQ page will be updated with new code samples, requirements, and capability descriptions.

    2. As the forum grows we will be taking answered questions out of the API forum to add to this FAQ to make certain content easier to find.



As always, if you have questions feel free to start a post and we will see it and respond.

 


 

  • This reply was deleted by Jonathan.Pechta (IBM) 2014-05-09T20:13:53Z. Reason for deletion: Deleting an edit note.
  • Jonathan.Pechta (IBM)
    22 Posts
    ACCEPTED ANSWER

    Re: QRadar REST API - Frequently Asked Questions

    ‏2014-06-05T19:36:10Z  in response to Jonathan.Pechta (IBM)

    Edited the FAQ to include Ariel_Query_Language_(AQL).pdf.  This document only applies to QRadar 7.2.2 and can be found in the user interface under  /ariel > POST /Searches. The purpose of the document is to instruct API users on how to create new Ariel searches using an Ariel Query Language (AQL) expression.

     

    -----

    Our support webinars are coming soon. Vote on topics you are interested in. For more information, see our Webinar topic survey:  https://www.surveymonkey.com/s/QRadarOpenmic