add list_questions() documentation

Author: SeaBlooms

examples/README.md

@@ -129,6 +129,24 @@ This directory contains comprehensive examples demonstrating how to use the Jupi
 - `create_question()` - Create questions with J1QL queries
 - `list_questions()` - List all questions in the account
 
+### 9. **examples.py**
+**Purpose**: Comprehensive examples of all major SDK methods
+- Client setup and basic operations
+- Entity and relationship management
+- Integration and sync job operations
+- Alert rules and SmartClass operations
+- Questions management and analysis
+- Account parameter operations
+
+**Key Methods Demonstrated**:
+- All major SDK methods including:
+- `list_questions()` - List and analyze all questions in the account
+- `create_question()` - Create questions with various configurations
+- Entity lifecycle management methods
+- Relationship management methods
+- Integration and sync job methods
+- Alert rule and SmartClass methods
+
 ## 🚀 Getting Started
 
 ### Prerequisites
@@ -184,6 +202,13 @@ python 08_questions_management.py
 - Time-based queries
 - Complex multi-step queries
 
+### 📊 Questions Management
+- Question creation with J1QL queries
+- Question listing and analysis
+- Compliance metadata management
+- Question categorization and filtering
+- Question lifecycle management
+
 ### 🏗️ Entity Management
 - Entity creation with various property types
 - Entity updates and modifications
@@ -254,6 +279,25 @@ j1 = JupiterOneClient(
 )
 ```
 
+### Questions Analysis
+Examples show how to analyze questions data:
+```python
+# List all questions
+questions = j1.list_questions()
+
+# Analyze by compliance standards
+compliance_standards = {}
+for question in questions:
+    if 'compliance' in question and question['compliance']:
+        compliance = question['compliance']
+        if isinstance(compliance, dict) and 'standard' in compliance:
+            standard = compliance['standard']
+            compliance_standards[standard] = compliance_standards.get(standard, 0) + 1
+
+# Find questions by tags
+security_questions = [q for q in questions if 'tags' in q and q['tags'] and any('security' in tag.lower() for tag in q['tags'])]
+```
+
 ## 📝 Notes
 
 ### Placeholder Values

examples/examples.py

@@ -568,3 +568,81 @@
 
 r = j1.create_update_parameter(name="ParameterName", value="stored_value", secret=False)
 print(json.dumps(r, indent=1))
+
+# list_questions
+list_questions_r = j1.list_questions()
+print("list_questions()")
+print(f"Total questions found: {len(list_questions_r)}")
+print(json.dumps(list_questions_r[:2], indent=1))  # Show first 2 questions
+
+# list_questions with filtering (if supported)
+# Note: The current implementation doesn't support filtering parameters,
+# but the GraphQL schema shows support for searchQuery, tags, etc.
+print("\nlist_questions() - Sample question details:")
+if list_questions_r:
+    sample_question = list_questions_r[0]
+    print(f"  Title: {sample_question.get('title', 'No title')}")
+    print(f"  ID: {sample_question.get('id', 'No ID')}")
+    print(f"  Description: {sample_question.get('description', 'No description')}")
+    print(f"  Tags: {sample_question.get('tags', [])}")
+    print(f"  Number of queries: {len(sample_question.get('queries', []))}")
+    if sample_question.get('queries'):
+        for i, query in enumerate(sample_question['queries']):
+            print(f"    Query {i+1}: {query.get('name', 'Unnamed')} - {query.get('query', 'No query')[:50]}...")
+else:
+    print("  No questions found in the account")
+
+# list_questions - analyze question types and compliance
+print("\nlist_questions() - Analysis:")
+if list_questions_r:
+    # Count questions by compliance standard
+    compliance_standards = {}
+    question_types = {}
+    
+    for question in list_questions_r:
+        # Analyze compliance standards
+        if 'compliance' in question and question['compliance']:
+            compliance = question['compliance']
+            if isinstance(compliance, dict) and 'standard' in compliance:
+                standard = compliance['standard']
+                compliance_standards[standard] = compliance_standards.get(standard, 0) + 1
+        
+        # Analyze question types by tags
+        if 'tags' in question and question['tags']:
+            for tag in question['tags']:
+                question_types[tag] = question_types.get(tag, 0) + 1
+    
+    print(f"  Total questions: {len(list_questions_r)}")
+    print(f"  Compliance standards found: {len(compliance_standards)}")
+    if compliance_standards:
+        print("    Standards:")
+        for standard, count in compliance_standards.items():
+            print(f"      {standard}: {count} questions")
+    
+    print(f"  Question categories (by tags): {len(question_types)}")
+    if question_types:
+        print("    Top categories:")
+        sorted_tags = sorted(question_types.items(), key=lambda x: x[1], reverse=True)[:5]
+        for tag, count in sorted_tags:
+            print(f"      {tag}: {count} questions")
+
+# list_questions - find specific types of questions
+print("\nlist_questions() - Finding specific questions:")
+if list_questions_r:
+    # Find security-related questions
+    security_questions = [q for q in list_questions_r if 'tags' in q and q['tags'] and any('security' in tag.lower() for tag in q['tags'])]
+    print(f"  Security-related questions: {len(security_questions)}")
+    
+    # Find compliance-related questions
+    compliance_questions = [q for q in list_questions_r if 'compliance' in q and q['compliance']]
+    print(f"  Compliance-related questions: {len(compliance_questions)}")
+    
+    # Find questions with variables
+    variable_questions = [q for q in list_questions_r if 'variables' in q and q['variables']]
+    print(f"  Questions with variables: {len(variable_questions)}")
+    
+    # Find questions with polling enabled
+    polling_questions = [q for q in list_questions_r if 'pollingInterval' in q and q['pollingInterval'] and q['pollingInterval'] != 'DISABLED']
+    print(f"  Questions with polling enabled: {len(polling_questions)}")
+
+print()

jupiterone/client.py

@@ -1247,7 +1247,7 @@ def fetch_downloaded_evaluation_results(self, download_url: str = None):
             return e
 
     def list_questions(self):
-        """List all defined Questions configured in J1 account Questions Library"""
+        """List all defined Questions configured in J1 Account Questions Library"""
         results = []
 
         data = {