Merge pull request #75 from CybercentreCanada/update/submit-options

Update/submit options

docs/integration/python.md

@@ -1,6 +1,6 @@
 # Python Client
 
-The Assemblyline python client facilitates issuing requests to Assemblyline.
+The Assemblyline Python client facilitates issuing requests to Assemblyline.
 
 ## Installing the client
 
@@ -73,8 +73,8 @@ You can instantiate the client by using the following snippet of Python code:
 
 ## Examples
 
-### Submit a file or URL for analysis
-There are two methods for sending a file/URL to Assemblyline for analysis: **Ingest** and **Submit**.
+### Submit a file, URL or SHA256 for analysis
+There are two methods for sending a file/URL/SHA256 to Assemblyline for analysis: **Ingest** and **Submit**.
 
 !!! attention "In most cases, you want to use the Ingest API via the CLI"
 
@@ -88,7 +88,7 @@ There are two methods for sending a file/URL to Assemblyline for analysis: **Ing
     **Submit**
 
     * High priority, low volume (5 concurrent submissions by default, this can be increased slightly in the user settings)
-    * You will need to wait for analysis to complete before submitting more
+    * You will need to wait for the analysis to complete before submitting more
     * Useful to support manual analysis
 
 !!! example "(Optional) Customizing your submission"
@@ -128,13 +128,15 @@ There are two methods for sending a file/URL to Assemblyline for analysis: **Ing
 
 !!! tip "For submitting a URL instead of a file, use the `url` argument instead of `path`"
 
+!!! tip "For submitting a SHA256 instead of a file, use the `sha256` argument instead of `path`"
+
 === "Ingest"
     The Ingest API supports three additional functionalities over the Submit API:
 
     * The ingest API is for high throughput submission (feeding the system)
     * By passing the argument `alert=True`, the system will generate an alert if the score is over 500
-    * By passing the argument `nq='notification_queue_name'`, you can use the client to poll a notification queue for a message indicating if the analysis has completed
-        * If you don't need to know about when the analysis completes, then you can omit the `nq` argument and ignore the subsequent code that interacts with the notification queue
+    * By passing the argument `nq='notification_queue_name'`, you can use the client to poll a notification queue for a message indicating if the analysis has been completed
+        * If you don't need to know when the analysis completes, then you can omit the `nq` argument and ignore the subsequent code that interacts with the notification queue
 
     ```python
     ingest_id = al_client.ingest(path='/pathto/file.txt', nq='my_queue_name', params=settings, metadata=my_meta)
@@ -192,12 +194,12 @@ In the following example, we want to retrieve the users who have made submission
 submission_results = al_client.search.facet.submission('params.submitter', query='times.submitted:[now-7d TO now]')
 ```
 
-## Using the Command-line Tool
-By installing the `assemblyline_client` PIP package, a command-line tool `al-submit` is installed.
+## Using the Command line Tool
+By installing the `assemblyline_client` PIP package, a command line tool `al-submit` is installed.
 In case you don't want to use Python code to interface with the Assemblyline client, you can use this tool instead.
 You can view the user options via `al-submit --help`.
 ??? example "(Optional) Configuration file example"
-    Rather than passing authentication and server details as parameters in a command-line, you can use a configuration file.
+    Rather than passing authentication and server details as parameters in a command line, you can use a configuration file.
     This configuration file should be placed at `~/.al/submit.cfg`. A template for this configuration
     file can be found below.
     NOTE: You can use `=` or `:` as the delimiter between key and value.

docs/user_manual/results.fr.md

@@ -71,7 +71,7 @@ Le bouton **Submission Details** [Détails de la soumission] est situé au haut
 
 ![Details](./images/report_viewdetails.png)
 
-Les détails de la soumission affichent les paramètres de la soumission, à savoir les services sélectionnés au moment où le fichier a été soumis et les [métadonnées](../../integration/python/#submit-a-file-or-url-for-analysis) de la soumission. La section la plus importante est celle qui contient le bouton.
+Les détails de la soumission affichent les paramètres de la soumission, à savoir les services sélectionnés au moment où le fichier a été soumis et les [métadonnées](../../integration/python/#submit-a-file-url-or-sha256-for-analysis) de la soumission. La section la plus importante est celle qui contient le bouton.
 
 
 ### Arborescence des fichiers d’extraction

docs/user_manual/results.md

@@ -73,7 +73,7 @@ The "Submission Details" button is located at the top of the submission report.
 ![Details](./images/report_viewdetails.png)
 
 Submission details will display submission parameters such as which services were selected when the file was submitted
-and submission [metadata](../../integration/python/#submit-a-file-or-url-for-analysis).
+and submission [metadata](../../integration/python/#submit-a-file-url-or-sha256-for-analysis).
 
 ### Extracted File Tree
 The extracted file tree section will show a view of all the files that were processed and extracted along with their respective score and file type.

docs/user_manual/submitting_file.fr.md

@@ -1,7 +1,7 @@
 # Soumettre un fichier aux fins d’analyse
 
 ## Soumission
-Il est facile de soumettre un fichier aux fins d’analyse. On peut le faire directement à partir de l’interface Web d’Assemblyline. En ce qui concerne l’automatisation et l’intégration, vous pouvez utiliser l’[REST API](../../integration/python/#submit-a-file-or-url-for-analysis).
+Il est facile de soumettre un fichier aux fins d’analyse. On peut le faire directement à partir de l’interface Web d’Assemblyline. En ce qui concerne l’automatisation et l’intégration, vous pouvez utiliser l’[REST API](../../integration/python/#submit-a-file-url-or-sha256-for-analysis).
 
 ![File submission](./images/submit.png)
 
@@ -16,7 +16,7 @@ Vous pouvez cliquer sur **Select a file to scan** [Sélectionner un fichier à a
 ## Options
 D’autres options de soumission sont offertes et permettent de faire ce qui suit :
 
-- sélectionner les catégories de services ou les services particuliers à utiliser aux fins d’analyse; 
+- sélectionner les catégories de services ou les services particuliers à utiliser aux fins d’analyse;
 - préciser les options de configuration des services (p. ex. fournir un mot de passe ou l’expiration d’une analyse dynamique).
 
 | Ignore filtering services | [Ignorer les services de filtrage] Contourne les services de mises en liste blanche |
@@ -33,4 +33,3 @@ D’autres options de soumission sont offertes et permettent de faire ce qui sui
 Une fois le fichier soumis dans Assemblyline, le système procédera automatiquement à plusieurs vérifications afin de déterminer la meilleure façon de le traiter. Le modèle d’analyse récursive est l’une des fonctionnalités les plus puissantes d’Assemblyline. Les maliciels et les documents malveillants utilisent souvent plusieurs couches d’obscurcissement. L’analyse récursive permet au système de supprimer ces couches et de poursuivre l’analyse du fichier. Il en résulte souvent un script en texte clair ou un maliciel non condensé qu’un antivirus conventionnel pourra détecter très facilement.
 
 ![Submit options](./images/processing.png)
-

docs/user_manual/submitting_file.md

@@ -1,12 +1,12 @@
 # Submitting a file for analysis
 
 ## Submission
-Submitting a file for analysis is really easy; it can be done directly using the Assemblyline WebUI. For automation and integration you can use the [REST API](../../integration/python/#submit-a-file-or-url-for-analysis).
+Submitting a file for analysis is easy; it can be done directly using the Assemblyline WebUI. For automation and integration you can use the [REST API](../../integration/python/#submit-a-file-url-or-sha256-for-analysis).
 
 ![File submission](./images/submit.png)
 
 ### Sharing and classification
-If your system is configured with a sharing control (TLP) or Classification configuration, available restriction can be selected by clicking on the Classification Banner.
+If your system is configured with a sharing control (TLP) or Classification configuration, the available restriction can be selected by clicking on the Classification Banner.
 
 ### Selecting a file to scan
 You can click the "Select a file to scan" or drag and drop a file to the area enclosed by the dashed line to add a file to be analyzed.
@@ -20,17 +20,16 @@ Additional submission options are available to:
 - Ignore result cache: Force re-analysis even if the same file had been scanned recently with the same service versions
 - Ignore dynamic recursion prevention: Disable iteration limit on a file
 - Profile current scan
-- Perform deep analysis: Provide maximum deobfuscation (**Highly recommended for known malicious or highly suspicious file to detect highly obfuscated content**)
+- Perform deep analysis: Provide maximum deobfuscation (**Highly recommended for known malicious or highly suspicious files to detect highly obfuscated content**)
 - Time to live: Time (in days) before the file is purged from the system
 
 ![Submit options](./images/submit_options.png)
 
 ## File analysis
-Once a file is submitted to Assemblyline, the system will automatically perform multiple checks to determine how to best 
-process the file. One of Assemblyline's most powerful functionalities is its recursive analysis model. Malware and 
-malicious documents often use multiple layers of obfuscation; recursive analysis allows the system to remove these 
-layers and keep analyzing the file. The end result is often a cleartext script or unpacked malware which traditional 
+Once a file is submitted to Assemblyline, the system will automatically perform multiple checks to determine how to best
+process the file. One of Assemblyline's most powerful functionalities is its recursive analysis model. Malware and
+malicious documents often use multiple layers of obfuscation; recursive analysis allows the system to remove these
+layers and keep analyzing the file. The result is often a cleartext script or unpacked malware which traditional
 anti-virus are very effective at detecting.
 
 ![Submit options](./images/processing.png)
-

docs/user_manual/submitting_sha256.fr.md

@@ -0,0 +1,35 @@
+# Soummission d'un hash SHA256 pour l'analyse
+
+## Soumission
+Soumettre un SHA256 pour analyse est très similaire à la soummision d'un URL; cela peut être fait directement dans l'interface graphique web d'Assemblyline. Pour l'automatisation et l'intégration vous pouvez utiliser l'API. [REST API](../../integration/python/#submit-a-file-url-or-sha256-for-analysis).
+
+![Soumission de fichier](./images/submit.fr.png)
+
+Cliquez sur l'onglet "URL/SHA256".
+
+![Soumission URL/SHA256](./images/submission.fr.png)
+
+### Partage et classification
+Si votre systême est configuré avec le contrôle de partage(TLP) ou la classification  de configuration, les restrictions disponibles peuvent être selectionné en cliquant sur la bannière de classification.
+
+### Choisir un SHA256 pour analyse
+Contrairement à la soumission par fichier où un fichier est glisser ou selectionné du disque, il suffit d'entrer dans la zone de texte d'entrée le SHA256 que vous voulez analyser en le copiant/collant, puis cliquer sur "ANALYSER"!
+
+### Note important par rapport aux soumissions SHA256 avec Assemblyline
+Par défault, soumettre un hash SHA256 dans Assemblyline pour analyse mandatera Assemblyline de chercher dans le storage de fichier pour un fichier existant soumis précédement ayant ce hash. Si le fichier en question existe, Assemblyline resoumettra ce fichier pour l'analyse. Si ce fichier n'existe pas dans le storage, alors la soumission échouera ou Assemblyline tentera d'utiliser une source externe (si configuré) en cherchant l'existance de ce hash. Si le hash existe via la source externe comme Malware Bazaar, alors Assemblyline téléchargera le fichier via cette source et soumettra ce fichier pour analyse. Vous pouvez configurer ce paramètre dans votre déploiement k8s sous la section `ui`: https://cybercentrecanada.github.io/assemblyline4_docs/odm/models/config/#externalsource.
+
+![Soumission de hash](./images/submit_hash.fr.png)
+
+## Options
+Options de soumission additionels non limité à:
+
+- Choisir quelle(s) catégorie(s) de services ou quel(s) service(s) spécifique(s) à utiliser pour l'analyse
+- Spécifier les paramètres de soumission des services (example: indiquer un mot de passe à utiliser, ou encore un temps limite pour l'analyse dynamique)
+- Ignorer la filtration des services: Ne pas prendre compte des services de sûreté
+- Ignoner les résultats en cache: Forcer la re-soumission même si le même fichier a été analyser récemment avec les mêmes versions de service
+- Ignorer la prévention de la récurssion dynamique: Déactiver l'itération limite sur un fichier
+- Profiler l'analyse courante
+- Effectuer une analyse approfondie: Permet un decortiquate maximal (**Grandement recommendé pour les fichiers connus malveillants ou très suspicieux afin de détection le contenu camouflé**)
+- Temps de vie: Temps (en jours) avant que le fichier soit effacé du système.
+
+![Options de soumission](./images/submit_options.fr.png)

docs/user_manual/submitting_sha256.md

@@ -0,0 +1,35 @@
+# Submitting a SHA256 for analysis
+
+## Submission
+Submitting a SHA256 for analysis is very similar to submitting a URL; it can be done directly using the Assemblyline WebUI. For automation and integration you can use the [REST API](../../integration/python/#submit-a-file-url-or-sha256-for-analysis).
+
+![File submission](./images/submit.png)
+
+Just click on the "URL/SHA256" tab.
+
+![URL/SHA256 submission](./images/submit_url.png)
+
+### Sharing and classification
+If your system is configured with a sharing control (TLP) or Classification configuration, the available restriction can be selected by clicking on the Classification Banner.
+
+### Choosing a SHA256 to scan
+Rather than dragging and dropping a file or selecting a file from your local drive, you input the SHA256 that you want to scan by typing/pasting it into the "URL/SHA256 To Scan" text box and clicking "SCAN"!
+
+### An important thing to note about SHA256 submissions in Assemblyline
+As a default, submitting a SHA256 hash to Assemblyline for analysis will prompt Assemblyline to check its file store to see if the SHA256 exists for any file that Assemblyline has previously seen. If the file exists, then Assemblyline will resubmit that file for analysis. If the file does not exist, then the submission will either fail or Assemblyline will use an external source (if configured) to query the existence of the hash. If the SHA256 is present on an external source like Malware Bazaar, then Assemblyline will download the file from that source and submit that file for analysis. You can set this up in your k8s deployment configuration under the `ui` component: https://cybercentrecanada.github.io/assemblyline4_docs/odm/models/config/#externalsource.
+
+![Submit hash](./images/submit_hash.png)
+
+## Options
+Additional submission options are available to:
+
+- Select which service categories or specific services to use for the analysis
+- Specify service configuration options (such as providing a password, or dynamic analysis timeout)
+- Ignore filtering services: Bypass safelisting services
+- Ignore result cache: Force re-analysis even if the same file had been scanned recently with the same service versions
+- Ignore dynamic recursion prevention: Disable iteration limit on a file
+- Profile current scan
+- Perform deep analysis: Provide maximum deobfuscation (**Highly recommended for known malicious or highly suspicious files to detect highly obfuscated content**)
+- Time to live: Time (in days) before the file is purged from the system
+
+![Submit options](./images/submit_options.png)

docs/user_manual/submitting_url.fr.md

@@ -0,0 +1,35 @@
+# Soumission d'un lien URL pour l'analyse
+
+## Soumission
+Soumettre un lien URL pour analyse est très similaire à la soumission de fichier; cela peut être fait directement dans l'interface graphique web d'Assemblyline. Pour l'automatisation et l'intégration il est possible d'utiliser l'API [REST API](../../integration/python/#submit-a-file-url-or-sha256-for-analysis).
+
+![Soumission de fichier](./images/submit.fr.png)
+
+Cliquer sur l'onglet "URL/SHA256".
+
+![Soumission d'URL/SHA256](./images/submit_url.fr.png)
+
+### Partage et classification
+Si votre systême est configuré avec le contrôle de partage(TLP) ou la classification  de configuration, les restrictions disponibles peuvent être selectionné en cliquant sur la bannière de classification.
+
+### Choisir un URL pour analyse
+Contrairement à la soumission par fichier où un fichier est glisser ou selectionné du disque, il suffit d'entrer dans la zone de texte d'entrée le lien URL que vous voulez analyser en le copiant/collant, puis cliquer sur "ANALYSER"!
+
+### Note important par rapport aux soumissions URL avec Assemblyline
+Puisqu'Assemblyline est un système de triage de fichier malveillant, il commence chaque soumission avec un fichier, même si vous soumettez un URL. La façon dont cela fonctionne est que lorsque vous soumettez un URL pour analyse, Assemblyline fera une requête de connection au URL soumit, téléchargera la ressource qui est hébergée à cet endroit et soumettra ce fichier pour analyse. S'il n'y a plus de ressource à cet endroit, ou si Assemblyline ne peut pas se connecter au server où le URL pointe, la soumission échouera.
+
+Ceci est important car si vous avez un URL qui héberge un fichier malveillant et que vous ne voulez pas exposer votre système Assemblyline au serveur duquel le URL pointe, il est recommandé de configurer un serveur proxy qui agira comme intermédiaire entre l'architecture d'Assemblyline et le serveur qui héberge un fichier malveillant. Vous pouvez configurer ce paramètre dans votre déploiement k8s sous la section `ui`: https://cybercentrecanada.github.io/assemblyline4_docs/odm/models/config/#ui. Le paramètre en question est `url_submission_proxies`.
+
+## Options
+Options de soumission additionels non limité à:
+
+- Choisir quelle(s) catégorie(s) de services ou quel(s) service(s) spécifique(s) à utiliser pour l'analyse
+- Spécifier les paramètres de soumission des services (example: indiquer un mot de passe à utiliser, ou encore un temps limite pour l'analyse dynamique)
+- Ignorer la filtration des services: Ne pas prendre compte des services de la liste sûre
+- Ignoner les résultats en cache: Forcer la re-soumission même si le même fichier a été analyser récemment avec les mêmes versions de service
+- Ignorer la prévention de la récurssion dynamique: Déactiver l'itération limite sur un fichier
+- Profiler l'analyse courante
+- Effectuer une analyse approfondie: Permet un decortiquate maximal (**Grandement recommendé pour les fichiers connus malveillants ou très suspicieux afin de détection le contenu camouflé**)
+- Temps de vie: Temps (en jours) avant que le fichier soit effacé du système.
+
+![Options de soumission](./images/submit_options.fr.png)