Microsoft File Share Plugin for Exact Data Match

This document explains how to configure the Microsoft File Share EDM v1.1.0 plugin with the Exact Data Match module of the Netskope Cloud Exchange platform. This plugin fetches CSV files from a Microsoft Windows server using either SMB or SFTP protocols, and generates Exact Data Match (EDM) hashes according to the defined plugin configurations.

Le plugin prend en charge la connectivité à double protocole : SMB (Server Message Block) pour le partage de fichiers Microsoft natif, et SFTP (SSH File Transfer Protocol) pour le transfert de fichiers sécurisé. Cette flexibilité permet aux organisations de choisir le protocole le plus approprié en fonction de leurs exigences de sécurité et de la configuration de leur infrastructure.

Conditions préalables

Pour compléter cette configuration, vous avez besoin de :

• Un locataire Netskope (ou plusieurs, par exemple des instances de production et de développement/test).
• Un locataire Netskope Cloud Exchange avec le plugin Tenant et le plugin Exact données Match déjà configurés.
• Serveur Microsoft Windows doté de fonctions de partage de fichiers en réseau.
• Fichiers CSV stockés sur le serveur Microsoft contenant les données à traiter pour la génération de hachages GED.
• Les informations d'identification de l'utilisateur approprié avec des autorisations de lecture pour les fichiers CSV sur le serveur Microsoft.

For the SMB Protocol

• Serveur Microsoft avec partage de réseau activé (service SMB/CIFS en cours d'exécution).
• Dossier partagé configuré avec les autorisations appropriées.
• Connectivité réseau au serveur Microsoft sur les ports SMB (généralement 445).

For the SFTP Protocol

• Serveur Microsoft avec le service OpenSSH activé et configuré.
• Service SSH en cours d'exécution et accessible depuis Cloud Exchange.
• Connectivité réseau au serveur Microsoft via le protocole SFTP (généralement port 22).

Prise en charge du plugin Microsoft File Share

Ce plugin récupère des fichiers CSV d'un serveur Microsoft Windows en utilisant les protocoles SMB ou SFTP et génère des hachages Exact données Match (EDM) selon les configurations définies par le plugin. Le plugin prend en charge la connectivité à double protocole pour une flexibilité et une compatibilité maximales avec différents environnements réseau.

Permissions et correspondances

Permissions du serveur Microsoft

Autorisations requises

Ces autorisations sont nécessaires pour la configuration du plugin :

For the SMB Protocol

• L'utilisateur du serveur Microsoft doit avoir un accès en lecture au dossier partagé et au fichier CSV.
• Connectivité réseau au serveur Microsoft sur le port 445.
• Service SMB/CIFS activé sur le serveur Microsoft.

For the SFTP Protocol

• L'utilisateur SSH doit avoir les droits de lecture pour le fichier CSV spécifié.
• Connectivité réseau avec le serveur Microsoft sur le port configuré (par défaut : 22).
• Le service OpenSSH est activé et fonctionne sur le serveur Microsoft.

from ..lib.smb.SMBConnection import SMBConnection
connection = SMBConnection(
    username=configuration.get("smb_username"),
    password=configuration.get("smb_password"),
    my_name="netskope_machine",
    remote_name=configuration.get("smb_machine_name"),
)

# Connect to the server
connection_result = connection.connect(
    ip=configuration.get("smb_server_ip"),
)

with open(csv_file_path, "wb") as file_object:
    if record_count:
	   # Partial file retrieval (for sample data)
        smb_connection.retrieveFileFromOffset(
            shared_directory_name,
            remote_file_path,
            file_obj=file_object,
            offset=0,
            max_length=record_count * 5 * 1024,
        )
    else:
        # Full file retrieval
        smb_connection.retrieveFile(
            shared_directory_name,
            remote_file_path,
            file_obj=file_object,
        )

smb_connection.close()

from ..lib import paramiko
ssh_connection = paramiko.SSHClient()
ssh_connection.set_missing_host_key_policy(paramiko.AutoAddPolicy())
ssh_connection.connect(
    hostname=configuration.get("sftp_server_ip"),
    username=configuration.get("sftp_username"),
    password=configuration.get("sftp_password"),
    port=configuration.get("sftp_port"),
)

with ssh_connection.open_sftp() as sftp_session:
    # SFTP operations here
    pass

with ssh_connection.open_sftp() as sftp_session:
    if record_count:
        # Partial file retrieval (for sample data)
        file_content = []
        with sftp_session.file(
            remote_file_path, "r"
        ) as remote_file:
            for _ in range(record_count + 1):
                record = remote_file.readline()
                if not record:
                    break
                file_content.append(record)
        with open(
            csv_file_path, "w", encoding="utf-8", newline="\n"
        ) as local_file:
            local_file.writelines(file_content)
    else:
        # Full file retrieval
        sftp_session.get(remote_file_path, csv_file_path)

ssh_connection.close()

Performance Matrix

Here is the performance reading conducted for fetching and sanitizing ~1M Rows (25 columns, per column ~50 characters long string, 1.3 GB size, Avg Column Uniqueness: ~96%, Avg Row Uniqueness: ~96%) CSV file on a Large CE instance with these specifications:

Performance Comparison

• SFTP protocol shows approximately 50% better performance compared to SMB.
• Sanitization reduces processing speed by approximately 55-65% for both protocols.
• SFTP is recommended for better performance and security.

Workflow

1. Configurez le serveur Microsoft Windows (SMB ou SFTP).
2. Configurez le plugin EDM Microsoft File Share.
3. Configurez le partage entre le plugin GED Microsoft File Share et le plugin GED Netskope.
4. Validez le plugin EDM Microsoft File Share.

Regardez une vidéo

Cliquer sur « play » pour regarder une vidéo.

Configurer le serveur Microsoft Windows

Pour le partage de fichiers SMB

1. Recherchez ou créez le dossier que vous souhaitez partager.
2. Faites un clic droit sur le dossier et sélectionnez Properties.
3. Go to the Sharing tab and click Advanced Sharing.
4. Vérifiez Share this folder.
5. Donnez un nom au partage si nécessaire.
6. Si vous le souhaitez, modifiez le nom du partage et cliquez sur Permissions pour définir le contrôle d'accès.
7. Dans la fenêtre Permissions, choisissez les utilisateurs ou les groupes auxquels vous voulez donner accès :
   • Si l'utilisateur requis n'est pas répertorié dans la section Noms de groupes ou d'utilisateurs, cliquez sur Add. Select Advanced cliquez sur Find Now et choisissez l'utilisateur dans la liste.
   • Une fois l'ajout effectué, confirmez que l'utilisateur apparaît dans la boîte de dialogue Permissions et assurez-vous qu'il dispose de l'autorisation Read pour le dossier.
8. Définissez le niveau d'accès (lecture, modification ou contrôle total).
9. Cliquez sur Apply et OK.
10. Enregistrez les modifications et vérifiez que le nom du dossier apparaît juste après le nom de l’ordinateur dans le Network Path.

Etapes pour activer OpenSSH sur un serveur Windows pour SFTP

Suivez ces étapes pour activer le service OpenSSH sur le serveur Windows :
https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse?tabs=gui

Configurer le plugin EDM Microsoft File Share

1. Dans Cloud Exchange, accédez à Settings > Plugin Store.

2. Recherchez et sélectionnez le plugin Microsoft File Share EDM v1.1.0.

   

3. Saisissez les informations de base :

   • Configuration Name: Enter a name appropriate for your integration.

     The configuration name you provide will be used to give the name to the generated hash file to share with the Netskope tenant. Be aware that if you later delete this configuration and create a new one with the same name, the hash file may already exist in the Netskope tenant. In such cases, attempting to push the hash file to the tenant will result in an error, as the file with the same name already exists. Consider using a unique name to avoid this issue.

   • Sync Interval: Adjust Sync Interval as per your requirement. (Default: 12 hours)

   

4. Protocol Selection: Choose the protocol to connect to the Microsoft server:

   • SMB: Protocol natively designed for Microsoft-based systems. Best for internal networks.
   • SFTP: Secure file transfer protocol. Comparatively faster and more secure. Requires OpenSSH service on Windows.

   

5. Click Next and enter the Configuration Parameters:

   • Configuration Parameters For SMB:

     • Server IP/Hostname: IP address or hostname of the Windows server.

     • Machine Name: Nom de machine NetBIOS du serveur Windows.

     • Username: Username with read access to the shared directory.

     • Password: Password associated with the username.

     • Shared Directory Name: Name of the shared directory.

     • CSV File Path: Path to the CSV file relative to the shared directory.

     • Delimiter: Single character delimiter used in the CSV/TXT file (e.g. comma, pipe, semicolon).

     • Remove Quotes: Mark as checked if your CSV encloses fields in double quotes, especially when values contain commas. Quoted fields will be parsed as single columns. Improper quote placement may cause rows to be skipped.

     

   • Configuration Parameters For SFTP:

     • Server IP/Hostname: IP address or hostname of the Windows server.

     • Username: Username with read access to the CSV file.

     • Password: Password associated with the username.

     • Port: Port to connect with OpenSSH service (Default: 22).

     • CSV File Path: Full path to the CSV file on the server.

     • Delimiter: Single character delimiter used in the CSV/TXT file (e.g. comma, pipe, semicolon).

     • Remove Quotes: Mark as checked if your CSV encloses fields in double quotes, especially when values contain commas. Quoted fields will be parsed as single columns. Improper quote placement may cause rows to be skipped.

     

     By default, quotes are treated as literal text. Enable Remove Quotes toggle if your CSV uses double quotes to encapsulate fields that contain commas (like "123 ABC Street, Suite 100"). This ensures the field is treated as a single column. Note that this mode requires strict CSV formatting. If a field starts with a quote, any character, including a space, following the closing quote but preceding the comma (like "Word",) will cause the row to be skipped.

6. Click Next and enter the Hash Generation and Sanitization Parameters:

   • Select les options appropriées pour les opérations d'assainissement et de génération de hachage :

     • Sanitization (Name Column): Sanitize the content by checking the Name Column checkbox. (Default: Unchecked). The Sanitization Process performs the following actions:
       • One character: The cell will be marked as invalid if it contains only one character.
       • Digits: Cells containing digits will be marked as invalid.
       • Stopwords: Cells that match a stopword from the list will be marked as invalid (This works only if the Remove stopwords checkbox is checked).
       • Non-alphanumeric characters: Remove all special characters to validate the cell.
     • La génération de hachages est divisée en deux parties :
       • Normalization: Select the value from dropdown to normalize the data value. (Default: None)
       • Create Dictionary: Select value from dropdown to create dictionary of unique values for selected field that can be used in DLP rule in netskope tenant. (Default: None)

   • Remove Stopwords: Mark as checked if you want to remove certain stopwords as part of the sanitization process.(Default:Unchecked) Ensure that Name Column is checked for the applicable field to reflect the changes.

   Note

   • Utilisez le paramètre de normalisation pour normaliser les résultats récupérés. Par exemple, un numéro tel que 123-45-6789 ou 123 45 6789 sera traité comme 123456789. Les normalisations numériques ignorent des caractères tels que les points, tirets et espaces. Une normalisation de chaîne ignore la sensibilité des lettres majuscules.
   • N'utilisez l'option Créer un dictionnaire qu'en cas de nécessité, car cette opération est gourmande en ressources et peut avoir un impact sur les performances du système. Choisissez cette option de manière réfléchie pour une efficacité optimale.

   

7. Click Next. Preview the sanitization sample output by clicking Preview Good File or Preview Bad File.

   

   If you are using the plugin with sanitization On, then the performance may be differ due to extra processing.

8. Proceed without sanitization: Uncheck this option to proceed with sanitization. (Default: Checked)

   Toutes les données seront prises en compte pour la génération du hachage si cette option n'est pas cochée; dans le cas contraire, seul le contenu du bon fichier sera pris en compte pour la génération du hachage.

9. Click Save. You will be redirected to Exact Data Match > Plugins page where you can see your configured plugin.

   

Configurer le partage pour Microsoft File Share

Une configuration de partage est utilisée pour partager les hachages EDM générés avec la plate-forme de destination. Pour partager des hachages EDM avec Netskope Tenant, créez une configuration de partage en suivant ces étapes :

1. Allez à Exact Data Match > Sharing et cliquez sur Add Sharing Configuration.

   

2. Configurez les paramètres de partage :

   • Source Configuration: Select the configured Microsoft File Share EDM plugin.
   • Destination Configuration: Select une destination où EDM Hash sera partagé.
   • Target: La valeur est automatiquement définie en fonction de la configuration de la destination sélectionnée.

   

3. Cliquez sur Save.

Validate the Plugin EDM Microsoft File Share

Valider dans Cloud Exchange

To validate the pulling of the configured plugin in Cloud Exchange, go to Settings > Logging and search for the Microsoft File Share EDM plugin logs.

You can verify the plugin operation from the logs available at Logging in Cloud Exchange:

Les valeurs d'état sont les suivantes :

• Scheduled: Indicates that the sharing has been configured, and the pull and push operations are waiting in the queue for processing.
• Generating Hash: Indicates that the hash generation process has started. This stage includes fetching > validating > sanitization (if enabled) > generating hash.
• Uploading Hash: Indicates that uploading the hash to the destination configuration has started.
• Upload Completed: Indique que les hachages sont téléchargés dans la configuration de destination.
• Checking Apply Status: Checking the apply status of hashes to the destination configuration.
• Apply In Progress: The hash process has started and is in progress on the destination.
• Completed: Indicates that the hash file has been pushed successfully to the destination configuration.
• Failed: Indicates that the final result of the action has failed to execute. The actions are Generating Hash/Uploading Hash/Checking Apply Status.

Shared EDM hashes can be verified from the logs available at Logging in Cloud Exchange:

Validate in the Netskope Tenant

Pour garantir la transmission des hachages de GED au locataire Netskope à partir du site Cloud Exchange:

1. Connectez-vous à votre locataire Netskope, allez à Policies > DLP.

   

2. Cliquez sur Edit Rules et sélectionnez Data Loss Prevention.

   

3. On the Exact Match tab, a list of files is shown.

   

Dépannage du plugin EDM Microsoft File Share

Impossible de configurer le plugin de partage de fichiers Microsoft

Si vous ne parvenez pas à configurer le plugin Microsoft File Share EDM, cela peut être dû à l'une des raisons suivantes :

For the SMB Protocol

• Les informations d'identification SMB fournies sont incorrectes.
• Le service SMB/CIFS ne fonctionne pas sur le serveur Windows.
• Problèmes de connectivité réseau au port 445.
• Le dossier partagé n'est pas correctement configuré.
• L'utilisateur n'a pas les droits de lecture sur le répertoire partagé.

For the SFTP Protocol

• Les informations d'identification SSH fournies sont incorrectes.
• Le service OpenSSH ne fonctionne pas sur le serveur Windows.
• Problèmes de connectivité réseau au port 22.
• Le service SSH n'est pas correctement configuré.
• L'utilisateur n'a pas les droits de lecture pour le fichier CSV.

What to do:

For SMB Protocol:

1. Vérifiez les informations d'identification SMB et l'accès aux dossiers partagés : cmd net use \\\\server_ip\\shared_folder /user:username password

2. Vérifiez l'état du service SMB sur le serveur Windows : Get-Service -Name LanmanServer

3. Testez la connectivité du réseau : telnet server_ip 445

For SFTP Protocol:

1. Vérifiez les informations d'identification SSH : bash ssh username@server_ip -p port_number

2. Vérifiez l'état du service OpenSSH : Get-Service -Name sshd

3. Testez la connectivité du réseau : telnet server_ip 22

Problèmes de connexion spécifiques au protocole

SMB Connection Failures

Si les connexions SMB échouent :

What to do:

1. Activez SMB sur le serveur Windows s'il est désactivé : Enable-WindowsOptionalFeature -Online -FeatureName SMB1Protocol
2. Configurez le pare-feu Windows pour SMB : New-NetFirewallRule -DisplayName "SMB-In" -Direction Inbound -Protocol TCP -LocalPort 445
3. Vérifiez les autorisations du dossier partagé et assurez-vous que l'utilisateur a un accès en lecture.

SFTP Connection Failures

Si les connexions SFTP échouent :

What to do:

1. Installez le serveur OpenSSH s'il n'est pas installé : Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
2. Démarrez et configurez le service SSH : Start-Service sshd Set-Service -Name sshd -StartupType 'Automatic'
3. Configurez le pare-feu Windows pour SSH : New-NetFirewallRule -Name sshd -DisplayName 'OpenSSH Server (sshd)' -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22

Fichier CSV introuvable ou accès refusé

Si vous recevez des messages d'erreur concernant un fichier non trouvé ou un accès refusé.

What to do:

1. Vérifiez que le chemin d'accès au fichier CSV est correct et que le fichier existe.
2. Assurez-vous que l'utilisateur dispose des droits de lecture pour le fichier.
3. Vérifiez que le fichier n'est pas verrouillé par un autre processus.
4. Pour SMB : assurez-vous que le chemin d'accès est relatif au répertoire partagé.
5. Pour SFTP : assurez-vous que le chemin d'accès est le chemin absolu complet sur le serveur.

La génération de hachage échoue ou prend trop de temps

If hash generation fails or performance is poor.

What to do:

1. Vérifiez l'espace disque disponible sur Cloud Exchange (assurez-vous d'avoir au moins 2x la taille du fichier CSV).
2. Envisagez d'utiliser le protocole SFTP pour de meilleures performances.
3. Réduisez la taille du fichier CSV ou divisez-le en plusieurs fichiers plus petits.
4. Désactivez l'assainissement s'il n'est pas nécessaire pour améliorer les performances.
5. Surveillez les ressources du système pendant le traitement.

Échec de la configuration du partage

If sharing EDM hashes to Netskope Tenant fails.

What to do:

1. Vérifiez que la configuration de la destination est correcte.
2. Check network connectivity to the Netskope tenant.
3. Assurez-vous que le nom du fichier de hachage n'existe pas déjà dans le locataire.
4. Examinez les journaux pour y trouver des messages d'erreur spécifiques.

Comportements connus

• Les fichiers CSV volumineux peuvent nécessiter un temps de traitement et des ressources système importants.
• L'assainissement peut réduire la vitesse de traitement d'environ 65% mais améliore la qualité des données.
• La création de dictionnaires est gourmande en ressources et ne doit être utilisée qu'en cas de nécessité.
• Le plugin crée des fichiers temporaires pendant le traitement qui sont automatiquement nettoyés.
• Des dépassements de délai de connexion SSH peuvent se produire avec des fichiers très volumineux ; envisagez d'augmenter les valeurs de délai.
• L'utilisation de la mémoire augmente avec la taille du fichier CSV ; surveillez les ressources du système pendant le traitement de fichiers volumineux.
• Il peut être nécessaire de configurer les règles du pare-feu Windows pour les protocoles SMB et SFTP.

Limites

Each Netskope tenant has a limit of handling up to 5 staging files. If this maximum limit is reached, you may encounter the following error while sharing hashes:

EDM Netskope Exact Data Match [EDM Netskope] Received exit code 400, Error occurred while uploading EDM hashes of configuration Linux EDM to the configuration EDM Netskope. 

To resolve this error, you have to delete the existing files from staging.