Collecter les journaux URLScan IO

Compatible avec :

Google SecOps SIEM

Remarque : Cette fonctionnalité est couverte par les Conditions des offres avant disponibilité générale des conditions spécifiques au service Google Security Operations. Les fonctionnalités pré-DG (avant disponibilité générale) sont susceptibles de présenter une compatibilité limitée, et les modifications apportées à ces fonctionnalités peuvent ne pas être compatibles avec d'autres versions avant disponibilité générale. Pour en savoir plus, consultez les Instructions relatives aux services d'assistance technique Google SecOps et les Conditions spécifiques du service Google SecOps.

Ce document explique comment ingérer des journaux URLScan.IO dans Google Security Operations à l'aide d'Amazon S3.

Avant de commencer

Assurez-vous de remplir les conditions suivantes :

• Une instance Google SecOps
• Accès privilégié au locataire URLScan IO
• Accès privilégié à AWS (S3, IAM, Lambda, EventBridge)

Obtenir les prérequis URLScan IO

1. Connectez-vous à URLScan IO.
2. Cliquez sur l'icône de votre profil.
3. Sélectionnez Clé API dans le menu.
4. Si vous ne disposez pas encore d'une clé API :
   • Cliquez sur le bouton Créer une clé API.
   • Saisissez une description pour la clé API (par exemple, Google SecOps Integration).
   • Sélectionnez les autorisations pour la clé (pour un accès en lecture seule, sélectionnez l'autorisation Lecture).
   • Cliquez sur Générer une clé API.
5. Copiez et enregistrez les informations suivantes dans un emplacement sécurisé :
   • API_KEY : chaîne de clé API générée (format : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
   • URL de base de l'API : https://urlscan.io/api/v1 (cette valeur est constante pour tous les utilisateurs)
6. Notez les limites de quota de votre API :
   • Comptes gratuits : limités à 1 000 appels d'API par jour et 60 par minute
   • Comptes Pro : limites plus élevées en fonction du niveau d'abonnement
7. Si vous devez limiter les recherches aux analyses de votre organisation uniquement, notez les éléments suivants :
   • Identifiant utilisateur : votre nom d'utilisateur ou votre adresse e-mail (à utiliser avec le filtre de recherche user:)
   • Identifiant de l'équipe : si vous utilisez la fonctionnalité Équipes (à utiliser avec le filtre de recherche team:)

Configurer un bucket AWS S3 et IAM pour Google SecOps

1. Créez un bucket Amazon S3 en suivant ce guide de l'utilisateur : Créer un bucket.
2. Enregistrez le nom et la région du bucket pour référence ultérieure (par exemple, urlscan-logs-bucket).
3. Créez un utilisateur en suivant ce guide de l'utilisateur : Créer un utilisateur IAM.
4. Sélectionnez l'utilisateur créé.
5. Sélectionnez l'onglet Informations d'identification de sécurité.
6. Cliquez sur Créer une clé d'accès dans la section Clés d'accès.
7. Sélectionnez Service tiers comme Cas d'utilisation.
8. Cliquez sur Suivant.
9. Facultatif : Ajoutez un tag de description.
10. Cliquez sur Créer une clé d'accès.
11. Cliquez sur Télécharger le fichier CSV pour enregistrer la clé d'accès et la clé d'accès secrète pour référence ultérieure.
12. Cliquez sur OK.
13. Sélectionnez l'onglet Autorisations.
14. Cliquez sur Ajouter des autorisations dans la section Règles relatives aux autorisations.
15. Sélectionnez Ajouter des autorisations.
16. Sélectionnez Joindre directement des règles.
17. Recherchez la règle AmazonS3FullAccess.
18. Sélectionnez la règle.
19. Cliquez sur Suivant.
20. Cliquez sur Ajouter des autorisations.

Configurer la stratégie et le rôle IAM pour les importations S3

1. Dans la console AWS, accédez à IAM > Stratégies.
2. Cliquez sur Créer une règle> onglet "JSON".

3. Saisissez la règle suivante :

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "AllowPutObjects",
         "Effect": "Allow",
         "Action": "s3:PutObject",
         "Resource": "arn:aws:s3:::urlscan-logs-bucket/*"
       },
       {
         "Sid": "AllowGetStateObject",
         "Effect": "Allow",
         "Action": "s3:GetObject",
         "Resource": "arn:aws:s3:::urlscan-logs-bucket/urlscan/state.json"
       }
     ]
   }
   

   • Remplacez urlscan-logs-bucket si vous avez saisi un autre nom de bucket.

4. Cliquez sur Suivant > Créer une règle.

5. Accédez à IAM > Rôles > Créer un rôle > Service AWS > Lambda.

6. Associez la règle nouvellement créée.

7. Nommez le rôle urlscan-lambda-role, puis cliquez sur Créer un rôle.

Créer la fonction Lambda

1. Dans la console AWS, accédez à Lambda > Fonctions > Créer une fonction.
2. Cliquez sur Créer à partir de zéro.

3. Fournissez les informations de configuration suivantes :

   Paramètre	Valeur
   Nom	urlscan-collector
   Durée d'exécution	Python 3.13
   Architecture	x86_64
   Rôle d'exécution	urlscan-lambda-role

4. Une fois la fonction créée, ouvrez l'onglet Code, supprimez le stub et saisissez le code suivant (urlscan-collector.py) :

   import json
   import os
   import boto3
   from datetime import datetime, timedelta
   import urllib3
   import base64
   
   s3 = boto3.client('s3')
   http = urllib3.PoolManager()
   
   def lambda_handler(event, context):
       # Environment variables
       bucket = os.environ['S3_BUCKET']
       prefix = os.environ['S3_PREFIX']
       state_key = os.environ['STATE_KEY']
       api_key = os.environ['API_KEY']
       api_base = os.environ['API_BASE']
       search_query = os.environ.get('SEARCH_QUERY', 'date:>now-1h')
       page_size = int(os.environ.get('PAGE_SIZE', '100'))
       max_pages = int(os.environ.get('MAX_PAGES', '10'))
   
       # Load state
       state = load_state(bucket, state_key)
       last_run = state.get('last_run')
   
       # Prepare search query
       if last_run:
           # Adjust search query based on last run
           search_time = datetime.fromisoformat(last_run)
           time_diff = datetime.utcnow() - search_time
           hours = int(time_diff.total_seconds() / 3600) + 1
           search_query = f'date:>now-{hours}h'
   
       # Search for scans
       headers = {'API-Key': api_key}
       all_results = []
   
       for page in range(max_pages):
           search_url = f"{api_base}/search/"
           params = {
               'q': search_query,
               'size': page_size,
               'offset': page * page_size
           }
   
           # Make search request
           response = http.request(
               'GET',
               search_url,
               fields=params,
               headers=headers
           )
   
           if response.status != 200:
               print(f"Search failed: {response.status}")
               break
   
           search_data = json.loads(response.data.decode('utf-8'))
           results = search_data.get('results', [])
   
           if not results:
               break
   
           # Fetch full result for each scan
           for result in results:
               uuid = result.get('task', {}).get('uuid')
               if uuid:
                   result_url = f"{api_base}/result/{uuid}/"
                   result_response = http.request(
                       'GET',
                       result_url,
                       headers=headers
                   )
   
                   if result_response.status == 200:
                       full_result = json.loads(result_response.data.decode('utf-8'))
                       all_results.append(full_result)
                   else:
                       print(f"Failed to fetch result for {uuid}: {result_response.status}")
   
           # Check if we have more pages
           if len(results) < page_size:
               break
   
       # Write results to S3
       if all_results:
           now = datetime.utcnow()
           file_key = f"{prefix}year={now.year}/month={now.month:02d}/day={now.day:02d}/hour={now.hour:02d}/urlscan_{now.strftime('%Y%m%d_%H%M%S')}.json"
   
           # Create NDJSON content
           ndjson_content = '\n'.join([json.dumps(r, separators=(',', ':')) for r in all_results])
   
           # Upload to S3
           s3.put_object(
               Bucket=bucket,
               Key=file_key,
               Body=ndjson_content.encode('utf-8'),
               ContentType='application/x-ndjson'
           )
   
           print(f"Uploaded {len(all_results)} results to s3://{bucket}/{file_key}")
   
       # Update state
       state['last_run'] = datetime.utcnow().isoformat()
       save_state(bucket, state_key, state)
   
       return {
           'statusCode': 200,
           'body': json.dumps({
               'message': f'Processed {len(all_results)} scan results',
               'location': f"s3://{bucket}/{prefix}"
           })
       }
   
   def load_state(bucket, key):
       try:
           response = s3.get_object(Bucket=bucket, Key=key)
           return json.loads(response['Body'].read())
       except s3.exceptions.NoSuchKey:
           return {}
       except Exception as e:
           print(f"Error loading state: {e}")
           return {}
   
   def save_state(bucket, key, state):
       try:
           s3.put_object(
               Bucket=bucket,
               Key=key,
               Body=json.dumps(state),
               ContentType='application/json'
           )
       except Exception as e:
           print(f"Error saving state: {e}")
   

5. Accédez à Configuration > Variables d'environnement.

6. Cliquez sur Modifier > Ajouter une variable d'environnement.

7. Saisissez les variables d'environnement suivantes en remplaçant les valeurs par les vôtres :

   Clé	Exemple de valeur
   S3_BUCKET	urlscan-logs-bucket
   S3_PREFIX	urlscan/
   STATE_KEY	urlscan/state.json
   API_KEY	<your-api-key>
   API_BASE	https://urlscan.io/api/v1
   SEARCH_QUERY	date:>now-1h
   PAGE_SIZE	100
   MAX_PAGES	10

8. Une fois la fonction créée, restez sur sa page (ou ouvrez Lambda > Fonctions > votre-fonction).

9. Accédez à l'onglet Configuration.

10. Dans le panneau Configuration générale, cliquez sur Modifier.

11. Définissez Délai avant expiration sur 5 minutes (300 secondes), puis cliquez sur Enregistrer.

    Remarque : Le délai d'expiration est une limite supérieure stricte. Cela signifie que si la fonction est toujours en cours d'exécution lorsque le minuteur atteint cinq minutes, AWS Lambda l'arrête. Toute exécution plus courte se termine normalement. Vous n'êtes facturé que pour la durée d'exécution réelle.

Créer une programmation EventBridge

1. Accédez à Amazon EventBridge> Scheduler> Create schedule.
2. Fournissez les informations de configuration suivantes :
   • Planification récurrente : Tarif (1 hour).
   • Cible : votre fonction Lambda urlscan-collector.
   • Nom : urlscan-collector-1h.
3. Cliquez sur Créer la programmation.

Facultatif : Créez un utilisateur et des clés IAM en lecture seule pour Google SecOps

1. Accédez à la console AWS > IAM > Utilisateurs.
2. Cliquez sur Add users (Ajouter des utilisateurs).
3. Fournissez les informations de configuration suivantes :
   • Utilisateur : saisissez secops-reader.
   • Type d'accès : sélectionnez Clé d'accès – Accès programmatique.
4. Cliquez sur Créer un utilisateur.
5. Associez une stratégie de lecture minimale (personnalisée) : Utilisateurs > secops-reader > Autorisations > Ajouter des autorisations > Associer des stratégies directement > Créer une stratégie.

6. Dans l'éditeur JSON, saisissez la stratégie suivante :

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["s3:GetObject"],
         "Resource": "arn:aws:s3:::urlscan-logs-bucket/*"
       },
       {
         "Effect": "Allow",
         "Action": ["s3:ListBucket"],
         "Resource": "arn:aws:s3:::urlscan-logs-bucket"
       }
     ]
   }
   

7. Définissez le nom sur secops-reader-policy.

8. Accédez à Créer une règle > recherchez/sélectionnez > Suivant > Ajouter des autorisations.

9. Accédez à Identifiants de sécurité> Clés d'accès> Créer une clé d'accès.

10. Téléchargez le CSV (ces valeurs sont saisies dans le flux).

Configurer un flux dans Google SecOps pour ingérer les journaux URLScan IO

1. Accédez à Paramètres SIEM> Flux.
2. Cliquez sur Add New Feed (Ajouter un flux).
3. Dans le champ Nom du flux, saisissez un nom pour le flux (par exemple, URLScan IO logs).
4. Sélectionnez Amazon S3 V2 comme type de source.
5. Sélectionnez URLScan IO comme type de journal.
6. Cliquez sur Suivant.
7. Spécifiez les valeurs des paramètres d'entrée suivants :
   • URI S3 : s3://urlscan-logs-bucket/urlscan/
   • Options de suppression de la source : sélectionnez l'option de suppression de votre choix.
   • Âge maximal des fichiers : incluez les fichiers modifiés au cours des derniers jours. La valeur par défaut est de 180 jours.
   • ID de clé d'accès : clé d'accès utilisateur ayant accès au bucket S3.
   • Clé d'accès secrète : clé secrète de l'utilisateur ayant accès au bucket S3.
   • Espace de noms de l'élément : espace de noms de l'élément.
   • Libellés d'ingestion : libellé appliqué aux événements de ce flux.
8. Cliquez sur Suivant.
9. Vérifiez la configuration de votre nouveau flux sur l'écran Finaliser, puis cliquez sur Envoyer.

Vous avez encore besoin d'aide ? Obtenez des réponses de membres de la communauté et de professionnels Google SecOps.