IBM Security QRadar

 View Only

Managing Network Hierarchy: The Art, The Legend, and... A Python Script? - Introducing NHSuite for QRadar (contrib)

By Pascal Weber posted Tue October 17, 2023 09:23 AM


Managing Network Hierarchy: The Art, The Legend, and... A Python Script? - Introducing NHSuite for QRadar (contrib)

Introducing NHSuite for QRadar (contrib)

In the fast-paced arena of cybersecurity and monitoring, keeping up isn't just essential; it's a survival trait 🧠

Now, for those vintage lovers 📻 who've been cozying up with IBM's QRadar for quite some time, you'll fondly remember the free QRadar network Hierarchy app. Ah, those were the days, weren’t they? 
But, like all good things, our free treasured app decided to play hide-and-seek and disappeared from the free section of app exchange! 🕵️‍♂️ 

@Ralph Belfiore dropped some wisdom 🧙 on us with his excellent article, "Network Hierarchy Management", published on November 10, 2022. His suggestion? Manually use the API ⚙️. Accurate? Yes. Handy? Depends on how you feel.

To bridge this tech-gap and inject some of that old charm back, I crafted a Python script 🛠 NHSuite 🛠 for myself first and decided to share to our QRadar Community on github (usefull for our global other CI/CD project with QRadar, but it's another story 🙂).

The importance of Network Hierarchy in QRadar

🔔 The primary goal is to provide context for cybersecurity analysts!

IBM® Security QRadar® leverages its network hierarchy to gain insights into your network traffic, offering a holistic view of all activities across your setup.
Interestingly, your network hierarchy in QRadar doesn't necessarily have to mirror the physical structure of your actual network. Instead, QRadar accommodates any structure defined by IP address ranges. This flexibility allows you to categorize your network based on various factors, be it geographical location, business segments, roles, or even specific traffic trends. By doing so, you can distinctly recognize network activities and apply robust security protocols. It's crucial to note that QRadar identifies every network within this hierarchy as local. To avoid any misinterpretations or false alarms, always ensure your network hierarchy is current.
The current setup of the Network Hierarchy is designed to support most standard networks. If you require more accurate or specific coordinate information for a public IP address, consider updating the IP addresses in the Network Hierarchy to better reflect your organization's requirements. Additionally, if your organization uses geographic data 📍 for private IP address ranges, think about incorporating country, latitude, and longitude details into the Network Hierarchy for those non-routable IP addresses. By embedding this geographic information for private IPs in the QRadar Network Hierarchy, you can enable advanced search functions for these IP ranges (like GEO::LOOKUP 🔍 or GEO::DISTANCE 📏) , get the flag on log activity, and give administrators additional rule options.
Before delving into the functionalities of the 🛠 NHSuite 🛠, let's underscore the importance of network hierarchy:
  • 🏷️ Asset Classification: By defining your network topology in QRadar, assets can be automatically classified, aiding in better asset identification.
  • 📏 Rule Logic: Rules can be configured to understand the context based on the network hierarchy. This can help in reducing false positives by understanding if an activity is internal-to-internal, internal-to-external, etc.
  • ⚙️ Flow Processing: Helps in better understanding and visualizing network traffic patterns and flow directions (e.g., inbound, outbound).
  • 📈 Contextual Analysis: Offers a more granular insight into incidents by providing context on where in the network topology an activity or offense took place.

In essence, the network hierarchy in QRadar helps users gain a better contextual understanding of their environment, optimizing security monitoring and incident response. It's absolutely necessary on a QRadar deployment and have to be part of your evolution and change management.

You can also take a tour on the documentation : Guidelines for defining your network hierarchy

NHSuite for QRadar: A brief Overview


👉 Usage : --help --help

📤 Export : Using -e or --export-file parameter

📥 Import : Using -i or --import-file parameter

🌐 Domain information :  Using --check-domain parameter

⚙️ System information : Using the --check-version parameter

Core functionalities

  • Streamlined Export and Import:
    The tool permits seamless export of the network hierarchy into a universally accessible CSV format. Additionally, it supports the import of pre-defined network hierarchies, ensuring easy migration, restoration or update.
    • Export :
      👉 Using -e or --export-file parameter -e

      Here is the result (example) : cat my-nh.csv
      cat my-nh.csv
    • Import:
      👉 Using -i or --import-file parameter -i

      On this example, safety parameter is "on", so before import the NH is backuped with a timestamp on the safety folder.

      Note that the import feature has some interesting controls for Validating Data Formats :

         🌍 Check validity of location data (latitude and longitude format).
         🏴 Check country code format.
         🏴 Validate name format.
         🔗 Validate CIDR notation.
         📁 Validate group naming format.

    • File structure for import:
      id - Integer - The ID of the network object.
      group - String - The group of the network object.
      name - String - The name of the network object.
      cidr - String - The CIDR range of the network object.
      description - String - The description of the network object.
      domain_id - Integer - The domain ID of the network object.
      location - Optional -  The Geo location of the network object => Format with quotes mandatory "Latitude, Longitude"  : "49.1191,6.1744"
      country_code - Optional - String - The country code of the network object =>  ISO 3166-1 alpha-2 standard : FR, US, DE, IT, LU

    • Sample format :
      86,Canada_Network,Vancouver,,Remote network to the city of Totem Poles,6,"49.3027,-123.1417",CA
      87,Net-catchall-10-172-192,Net_10_0_0_0,,RFC 1918 Single class A address Range,0,N/A,N/A
      88,Net-catchall-10-172-192,Net_172_16_0_0,,RFC 1918 Single class B address Range,0,N/A,N/A
      89,Net-catchall-10-172-192,Net_192_168_0_0,,RFC 1918 Single class C adress ranges,0,N/A,N/A
      90,DMZ,Internal,,Internal DMZ Server choucroute,0,N/A,N/A
      91,DMZ,External,,External DMZ Server cassoulet,0,N/A,N/A
      92,VPN_Addresses_Space,VPN_Addresses_Space,,Network for VPN user,0,N/A,N/A
      93,Proxy_Servers,Proxy_Servers,,Proxy Server Zone,0,N/A,N/A
      94,NAT_Ranges,NAT_Ranges,,Default NAT Network,0,N/A,N/A
      95,Server_Network,Server_Network,,Development Server Network,0,N/A,N/A
      96,VoIP_Networks,VoIP_Networks,,Network for IAX PABX ,0,N/A,N/A
      97,Regulatory_Compliance_Servers,Regulatory_Compliance_Servers,,Network for compliance servers,0,N/A,N/A
      98,Wireless_Networks,all,,Default network for wireless users,0,N/A,N/A
      99,Metz_Network,Metz,,Remote network to the city of the Graoully,4,"49.1191,6.1744",FR
      100,Strasbourg_Network,Strasbourg-Sud,,Remote network to the city of La petite France,4,"48.5819,7.7509",FR
      101,Nancy_Network,Nancy,,Remote network to the city of the Stanislas Place,4,"48.6921,6.1844",FR
      102,Paris_Network,Paris,,Remote network to the city of Notre Dame,4,"48.8584,2.2945",FR
      103,Luxembourgville_Network,Luxembourgville,,Remote network to the city of the Grand Ducal Palace,1,"49.6113,6.1303",LU
      104,Weimar_Network,Weimar,,Remote network to the city of Goethe and Schiller,2,"50.9795,11.329",DE
      105,Berlin_Network,Berlin,,Remote network to the city of Brandenburg Gate,2,"52.5163,13.3779",DE
      106,Trier_Network,Trier,,Remote network to the city of Porta Nigra,2,"49.7596,6.6439",DE
      107,Nimes_Network,Nimes,,Remote network to the city of Arena of Nimes,4,"43.8369,4.3565",FR
      108,Roma_Network,Roma,,Remote network to the city of Coloseum,3,"41.8902,12.4924",IT
      109,US_Network,NewYork,,Remote network to the city of Miss Liberty,5,"40.6892,74.0445",US
      110,Canada_Network,Montreal,,Remote network to the city of Mount Royal Cross,6,"45.4972,73.6104",CA

    • Result after "deploy" on QRadar :

      Network Hierarchy Dialog Box from QRadar

  • Fetch and display domain information 
    In larger organizations with multiple domains, fetching domain-specific information becomes crucial. 🛠 NHSuite 🛠 integrates this functionality, directly interfacing with QRadar for real-time data retrieval.
    📌 This greatly assists in mapping the domain name to its corresponding ID in your file (if you use Domain).
    • 👉 Using --check-domain parameter to display Domain ID , Domain Name and Description for mapping your csv file if you use domain
      NHSuite --check-domain
  • Fetch and display QRadar System Information
    • 👉 Using the --check-version parameter to display qradar host version information
      NHSuite --check-version
  • Error Management:
    No tool is truly complete without comprehensive error handling. The tool is equipped to detect and log a wide range of errors, ensuring administrators of the platform are always informed of any inconsistencies or issues.
    • Using the error.log file generated


Access the 🛠 NHSuite 🛠 script on GitHub to delve into its code and documentation.

GitHub Link 

Here is the link of the full project - contribution are welcome - 

👉 Github Link :

Environment and prerequisite

The script can work directly on QRadar (Tested on 7.5.X) or on a remote Linux machine (Debian) meeting the requirements (preferred method)

Working directly on QRadar

  • Qradar > 7.5.0 (Python 3.6 (Use of f-strings))
The script has been designed with flexibility in mind. For those who have direct access and the required privileges, the script can operate directly on a QRadar system. We have verified its compatibility with QRadar versions 7.5.x. This direct method allows for streamlined integration and quick access to QRadar's features without the need for additional configurations.
However, there are some considerations when working directly on QRadar.

Working on a Remote Linux Machine (Preferred Method)

For a more isolated and controlled environment, we recommend executing the script on a remote 🐧 Linux machine. Our tests have particularly been positive on Debian-based systems.
This method has several advantages:
  • 🏝️ Isolation: Running the script remotely ensures that QRadar's primary functions remain undisturbed. There's no risk of unintentionally consuming excessive resources on the QRadar system.
  • 🤸 Flexibility: A separate Linux machine provides more freedom for customization, debugging, and script optimization. This can be especially beneficial when integrating the script with other tools or systems.
  • 🛡️ Security: Operating the script remotely can add a layer of security. By limiting direct access to the QRadar system, you can further safeguard against potential threats or mishaps.
📋 Requirements for the Remote Linux Machine:
  • Python Version: Ensure that Python is installed, preferably a version that supports f-strings (Python 3.6 and above).
  • Network Access: The remote machine should have network access to QRadar for API calls. Ensure that any firewalls or security groups allow for the necessary communication between the two systems.
  • Required Libraries: The script might rely on specific Python libraries. These should be installed and kept updated on the remote machine
  • Authentication: API authentication details, like tokens or credentials, should be securely managed. Consider using environment variables or secure configuration files.
🧪 Tested on my side on :
  • debian Bullseye (11.7)
  • Python 3.9.2
  • Requests==2.31.0
  • urllib3==1.26.5
In conclusion, while both methods have their merits, using a remote Linux machine offers a balance of security, flexibility, and efficiency.
Depending on your organization's infrastructure, security guidelines, and resource availability, you can choose the method that fits best.

How do i start ?

Clone the project from GitHub on your Linux instance with the git clone command : and the pre-requisite
Complete the config.txt according to your QRadar target, for example :
    "ip_QRadar": "qradardemo.zoldax.local",
    "auth": "a111b05c-cb81-4d2f-b286-2532f0c4baee",
    "Version": "17.0",
    "Accept": "application/json",
    "verify_ssl": "False",
    "ssl_cert_path": "None",
    "safety": "on"
  • 🌐 ip_QRadar: Specifies the IP address or domain name of the QRadar instance.
  • 🔑 auth: Authentication token for requests to the QRadar API (Admin > Authorized Services)
  • 🔢 Version: Denotes the targeted version of the QRadar API (17 For QRadar 7.5.x)
  • 📄 Accept: Sets the desired response format from QRadar API, typically application/json (Don't modify this one)
  • 🔒 verify_ssl: Decides if SSL certificate validation should occur when connecting to QRadar; not recommended to set as False in production.
  • 📂 ssl_cert_path: Path for a custom SSL certificate chain. If no custom certificate, or if verify_ssl is False, can be set to None (The cert file is the  CA pem file from your PKI)
  • 🛡️ safety:
    • ✔️ on: Backs up the current hierarchy before any changes (in the safety folder)
    • ⚠️ off: No backup made, caution advised especially in production.
Each parameter should be adjusted to align with the specifics of the user's QRadar environment and preferences.
Wrapping Up

🔒 In the realm of cybersecurity, the subtleties of managing network hierarchies are foundational. Sometimes, we have to find new solutions when familiar ones fade away. This tool is as one of those practical solutions, aiming to fill the void left by the Network Hierarchy app no more available on app exchange.

🛠️ At its heart, the tool aims to help — to offer a more straightforward approach to network hierarchy management, whether you're directly interfacing with QRadar or operating from a remote 🐧 Linux machine. Its functionalities, from error handling to data export, serve the user's needs without pretense.
🔄 Furthermore the tool isn't just about functionality—it's about adaptability. In the modern software development world, Continuous Integration and Continuous Deployment (CI/CD) have become foundational principles we saw that every day on the operational field. This ensure network hierarchy updates, backup, and changes to be consistently integrated, tested, and deployed to test environnement before production, and is part of a more global projet on my side 🌐.
🤝 It's also worth noting that, by hosting the script on GitHub, there's an open invitation for everyone to contribute and improve upon it. It's a collaborative effort, and the real value of the tool will be determined by the community's engagement and feedback 📢 (ideas for example : phpIPAM translation, etc...)
In summary, 🛠 NHSuite 🛠 is a humble attempt to make life a bit easier 🌟.
Hope you enjoy.

Happy Network Managing!

Cheers 🍻


#IBM Security#IBMChampions#IBMQRadar#QRadar-SIEM#Python




Thu November 02, 2023 08:18 AM

Very nice work!

Thu October 19, 2023 02:14 PM

Thanks Pascal for quality of content shared with the Security community. 

Tue October 17, 2023 09:28 AM

Thanks Pascal for sharing with the community.