Managing Network Hierarchy: The Art, The Legend, and... A Python Script? - 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 :
📤 Export : Using
📥 Import : Using
🌐 Domain information : Using
⚙️ System information : Using the
- 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.
- 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
- Fetch and display QRadar System Information
- 👉 Using the
--check-version parameter to display qradar host version information
- 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.
Here is the link of the full project - contribution are welcome -
👉 Github Link : https://github.com/zoldax/NHSuite
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
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 ?
config.txt according to your QRadar target, for example :
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)
- ✔️ 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.
🔒 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!