Merge pull request #104 from CybercentreCanada/new_uri

Documentation regarding the new URI feature

docs/user_manual/submitting_url.fr.md

@@ -15,10 +15,41 @@ Si votre systême est configuré avec le contrôle de partage(TLP) ou la classif
 ### 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.
+### Note important par rapport aux soumissions d'URL dans Assemblyline
+Soumetter une URL à travers l'interface web ou le client crée un fichier URI qui sera utilisé comme fichier initial dans une nouvelle soumission. Il est aussi possible de manuellement créer ce fichier afin de le soumettre à votre instance comme n'importe quel autre fichier. Le but d'un type de fichier URI dynamique est d'ouvrir la possibilité à des utiliser des services allant chercher de l'information sur des resources externe au système. L'utilisation principale est faite à travers des liens http et https qui peuvent héberger du contenu malicieux tel que la second phase d'une chaine d'exploitation. Lorsqu'un fichier URI est soumis, les bon services doivent être sélectionnés pour maximiser l'efficacité d'Assemblyline. Dans le cas d'un fichier http ou https, nous recommandons le module nommé URLDownloader.
 
-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`.
+### Le type de fichier URI
+Un fichier URI doit au minimum suivre la structure suivante:
+```yaml
+# Assemblyline URI file
+uri: <schéma>://<hôte>
+```
+Un fichier URI est un fichier yaml qui peut contenir plusieurs éléments supplémentaires afin de donner plus de détails aux modules pouvant les utiliser. Les deux portions les plus importantes sont la clé "uri", qui doit contenir un uri valide avec un schéma et un hôte, ainsi que le commentaire sur la première ligne, pour aider avec l'identification du fichier. Le schéma sera utilisé dans l'identification pour créer le type de fichier. Si le fichier contient `uri: http://site.com`, il sera identifié comme `uri/http` et s'il contient `uri: ftp://site.com`, il sera alors identifié comme `uri/ftp`. Cette distinction entre les fichiers URI permettent d'envoyer facilement les bons fichiers aux modules selon ce qu'ils peuvent faire. Dans le cas d'un fichier `uri/ftp`, il serait possible d'utiliser les éléments supplémentaire pour passer des informations importantes tel que le mode du server, en utilisant `passive: True`.
+
+Voici un autre example plus complet pour un fichier d'URI:
+```yaml
+# Assemblyline URI file
+uri: https://mb-api.abuse.ch/api/v1/
+data: query=get_info&hash=52307f9ce784496218f2165be83c2486ad809da98026166b871dc279d40a4d1f
+headers:
+  Content-Type: application/x-www-form-urlencoded
+method: POST
+```
+Ce fichier serait identifié comme fichier `uri/https` et les autres clés seront ignorées lors de l'identification. Les clés supplémentaires seront utilisés par URLDownloader pour effectuer les actions avec le plus de précision quant aux demande de l'utilisateur, ou du service ayant créé le fichier URI. Il serait possible d'y spécifier un user-agent, un referer ou un autre en-tête afin de respecter certains requis pour obtenir le fichier suivant d'un serveur qui filtre ses requêtes. À travers ces clés supplémentaires, il est possible de spécifier des méthodes tel que POST. Dans l'exemple précédent, il suffit de changer `query=get_info` à `query=get_file` afin de télécharger le fichier de MalwareBazaar!
+
+Étant donné que les fichiers d'URI sont spécifiques à Assemblyline, chaque fichier est ré-écrit lorsqu'il est envoyé à l'instance afin de s'assurer d'avoir le commentaire sur la première ligne, puis la clé `uri`, pour ensuite avoir toutes les clés supplémentaires dans l'ordre alphabetique. Cette ré-écriture est faite pour dé-dupliquer les fichiers qui peuvent être considérés identiques et optimiser la cache de résultats. Une clé telle que `extra_key: ["first", "second", "third", "fourth"]` garder le même ordre, mais sera convertie comme suit:
+```yaml
+extra_key:
+- first
+- second
+- third
+- fourth
+```
+
+### Fichiers URI et proxies
+Pour le moment, chaque module a besoin d'être configuré individuellement lorsqu'il est nécessaire de passer au travers d'un proxy. Le service URLDownloader peut être configuré pour supporter plusieurs proxies, ce qui donne le choix du proxy à l'utilisateur lors de la soumission. Dans le futur, il est planifié de normaliser la gestion des proxies dans Assemblyline afin d'avoir une configuration générale qui sera utilisée par tous les modules ayant besoin d'y accéder.
+
+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 auquel 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é à:

docs/user_manual/submitting_url.md

@@ -16,7 +16,38 @@ If your system is configured with a sharing control (TLP) or Classification conf
 Rather than dragging and dropping a file or selecting a file from your local drive, you input the URL 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 URL submissions in Assemblyline
-Since Assemblyline is a malware triage system, it starts every submission with a file, even if you submit a URL. The way that this works is if you submit a URL for analysis, Assemblyline will make a network request to the URL that you submitted, download the resource that is being hosted at that location, and submit that file for analysis. If there is no resource at the location anymore, or if Assemblyline cannot connect to the server where that URL was pointing, then the submission will fail.
+Submitting a URL through the interface, or through the client, will generate a URI file that will be the start of your submission. It is also possible to generate this file beforehand and send it directly to Assemblyline like any other file type. The goal of the dynamic URI file type is to be able to interact with outside resources. The current main use for it is handling of http/https links that we could get out of malicious file that would be important to fetch, for example to get a second stage payload. When submitting a URI file, you will need to have the right services selected. In the case of an http(s) file, we recommend using the URLDownloader service.
+
+### URI file type
+The URI file type has the following minimal structure:
+```yaml
+# Assemblyline URI file
+uri: <scheme>://<host>
+```
+It is a yaml file that can contain more elements for use-cases where the services can leverage them. The most important parts are the "uri" key in the yaml file, which needs to be a valid uri with a scheme and a host, and the comment on top, to help with Identification. The scheme is going to be used to create the file type, so if you are using `uri: http://site.com` it is going to be a file of type `uri/http` and if you are using `uri: ftp://site.com` then you will have a `uri/ftp`. This will make it possible to route to different services based on the scheme. In the case of `uri/ftp`, you will probably need more information, such as yaml keys like `passive: True`.
+
+The following is a more complete and complex example of a URI file:
+```yaml
+# Assemblyline URI file
+uri: https://mb-api.abuse.ch/api/v1/
+data: query=get_info&hash=52307f9ce784496218f2165be83c2486ad809da98026166b871dc279d40a4d1f
+headers:
+  Content-Type: application/x-www-form-urlencoded
+method: POST
+```
+The file type would be `uri/https` and the other yaml keys will be ignored during the identification. The extra keys in the yaml file can be used by the service handling this specific file to provide a more customized behavior, closer to what the user is asking. A specific user-agent, referer or other headers could be used to fetch a second stage for a server that would required specific values. Through those extra values, URLDownloader, now supports more methods like POST. A simple change from `query=get_info` to `query=get_file` in the data and the service should be downloading that file from MalwareBazaar!
+
+Since URI files are very specific to Assemblyline, we take the time to rewrite any incoming file so that the comment `# Assemblyline URI file` is on the first line, then the uri key, then all the other keys in alphabetical order. This is done to de-duplicate "identical" files and use caching. A key like `extra_key: ["first", "second", "third", "fourth"]` will have its order preserved and is going to be converted to the following:
+```yaml
+extra_key:
+- first
+- second
+- third
+- fourth
+```
+
+### URI files and proxies
+At the current time, each service that needs to go through a proxy will need an administrator to configure it. URLDownloader support proxies and may even be configured to let a user choose one of many configured proxies. In the future, we will look into normalizing this feature so that all services could leverage a central proxy selection.
 
 This is important because if you have a URL hosting malware and you do not want to expose your Assemblyline system to that server that the URL is pointing to, then we recommend you set up a proxy server to act as a middleman between your Assemblyline infrastructure and the server hosting malware. You can set this up in your deployment configuration under the [`ui` component](../..//odm/models/config/#ui). The item you are looking for is `url_submission_proxies`.