comms analyzer toolbox
1.3
Docker 映像提供了简化的 OSINT 工具集，用于使用 Elasticsearch 和 Kibana 导入和分析电子邮件 MBOX 文件以及其他 CSV 数据（例如文本消息）中的通信内容。这提供了一个命令，可以启动完整的 OSINT 分析软件堆栈，并将所有通信导入其中，准备使用 Kibana 和 ElasticSearch 进行分析。
该项目管理 Dockerfile 以生成一个映像，该映像在运行时启动 ElasticSearch 和 Kibana，然后可以选择使用容器中捆绑的以下工具导入通信数据：
重要的是，由于原始项目在该项目开发时尚未解决的突出问题，以下链接是原始项目的分支
从那里......好吧，您几乎可以分析和可视化有关您的通信的任何内容。享受。
在运行下面的示例之前，您需要安装 Docker。
Windows 注意：当您在构建之前在 Windows 上git clone这个项目时，请务必添加 git clone 标志--config core.autocrlf=input 。示例git clone https://github.com/bitsofinfo/comms-analyzer-toolbox.git --config core.autocrlf=input 。在这里阅读更多内容
安装 Docker 后，将启动命令行 shell 并输入以下内容来为工具箱构建 docker 映像：
docker build -t comms-analyzer-toolbox .
适用于 Windows 的 Docker 工具箱笔记
创建的default docker 机器虚拟机可能不足以开箱即用。您需要执行以下操作来增加本地虚拟机的 CPU 和内存
打开“Docker 快速启动终端”
删除默认机器： docker-machine rm default
重新创建它： docker-machine create -d virtualbox --virtualbox-cpu-count=[N cpus] --virtualbox-memory=[XXXX megabytes] --virtualbox-disk-size=[XXXXXX] default
故障排除错误：“最大虚拟内存区域 vm.max_map_count [65530] 太低，至少增加到 [262144]”
如果您在启动工具箱时看到此错误（该错误是从 Elasticsearch 报告的），您将需要在正在启动容器的 docker 主机上执行以下操作。
sysctl -w vm.max_map_count=262144
如果您使用 Docker Toolbox，则必须首先使用docker ssh default下 shell 进入 boot2docker VM 才能运行此命令。或者执行以下操作使其永久化：docker/machine#3859
对于 MBOX 文件中的每封电子邮件，每条消息都会成为 ElasticSearch 中的一个单独文档，其中所有电子邮件标头都作为单独字段进行索引，所有正文内容都进行索引并删除 html/css/js。
例如，导入索引的每封电子邮件都有以下字段可用于在 Kibana 中搜索和分析（还有更多）
一旦 Docker 在您的系统上可用，在运行comms-analyzer-toolbox之前，您需要一些 MBOX 格式的电子邮件进行分析。作为示例，以下是如何从 Gmail 导出电子邮件。
使用计算机上的网络浏览器登录您的 Gmail 帐户
前往：https://takeout.google.com/settings/takeout
在显示“下载您的数据”的屏幕上，在“选择要包含的数据”部分下，单击“不选择”按钮。这将使下面列出的所有“产品”变灰
现在向下滚动并找到标有“邮件”的灰色部分，然后单击右侧的X复选框。现在它会变成绿色，表示该数据已准备好供您下载。
向下滚动并单击蓝色的“下一步”按钮
保留“自定义存档格式”设置不变，然后单击“创建存档”按钮
现在，您将进入“我们正在准备您的档案”。屏幕。这可能需要几个小时，具体取决于您拥有的所有电子邮件的大小。
当存档可供下载时，您将收到一封来自 Google 的电子邮件。获取后，将 zip 文件下载到本地计算机的硬盘上，其名称将类似于takeout-[YYYMMMDDD..].zip
保存到硬盘后，您需要解压缩该文件，解压后，从 Gmail 导出的所有邮件都将保存在Takeout/Mail/文件夹中的mbox导出文件中，并且包含所有邮件的文件名位于： All mail Including Spam and Trash.mbox
您应该将此文件重命名为更简单的名称，例如my-email.mbox
记下.mbox文件的位置，因为您将在下面运行工具箱时使用它。
在运行下面的示例之前，您需要安装 Docker。
在计算机上打开终端或命令提示符并运行以下命令，在此之前，您需要将下面的PATH/TO/YOUR/email.mbox和PATH/TO/ELASTICSEARCH_DATA_DIR替换为本地系统上的正确路径。
注意：如果使用适用于 Windows 的 Docker Toolbox ：由于权限问题，下面所有已安装的卷都应位于c:Users[your username]...下的主目录下的某个位置。
docker run --rm -ti
--ulimit nofile=65536:65536
-v PATH/TO/YOUR/my-email.mbox:/toolbox/email.mbox
-v PATH/TO/ELASTICSEARCH_DATA_DIR:/toolbox/elasticsearch/data
comms-analyzer-toolbox:latest
python /toolbox/elasticsearch-gmail/src/index_emails.py
--infile=/toolbox/email.mbox
--init=[True | False]
--index-bodies=True
--index-bodies-ignore-content-types=application,image
--index-bodies-html-parser=html5lib
--index-name=comm_data
设置--init=True将删除并重新创建comm_data索引。设置--init=False将保留已存在的任何数据
控制台将记录正在发生的情况的输出，当系统启动时，您可以在桌面上打开 Web 浏览器并转到http://localhost:5601开始使用 Kibana 分析数据。注意：如果运行 docker toolbox； “localhost”可能不起作用，请执行docker-machine env default以确定您的 docker 主机 IP 地址，然后转到 http://[machine-ip]:5601"
在显示Configure an index pattern的第一个屏幕上，在标记为Index name or pattern字段中键入comm_data然后您将看到自动选择的date_ts字段，然后单击Create按钮。从那里 Kibana 就可以使用了！
启动按以下顺序执行几件事
当 mbox 导入程序运行时，您将在日志中看到以下条目，因为系统正在从 mbox 文件导入您的邮件
...
[I 170825 18:46:53 index_emails:96] Upload: OK - upload took: 467ms, total messages uploaded: 1000
[I 170825 18:48:23 index_emails:96] Upload: OK - upload took: 287ms, total messages uploaded: 2000
...
运行comms-analyzer-toolbox映像时，参数之一是调用采用以下参数的 elasticsearch-gmail 脚本。您可以根据需要调整上面的docker run命令以传递以下标志：
Usage: /toolbox/elasticsearch-gmail/src/index_emails.py [OPTIONS]
Options:
--help show this help information
/toolbox/elasticsearch-gmail/src/index_emails.py options:
--batch-size Elasticsearch bulk index batch size (default
500)
--es-url URL of your Elasticsearch node (default
http://localhost:9200)
--index-bodies Will index all body content, stripped of
HTML/CSS/JS etc. Adds fields: 'body',
'body_size' and 'body_filenames' for any
multi-part attachments (default False)
--index-bodies-html-parser The BeautifulSoup parser to use for
HTML/CSS/JS stripping. Valid values
'html.parser', 'lxml', 'html5lib' (default
html.parser)
--index-bodies-ignore-content-types
If --index-bodies enabled, optional list of
body 'Content-Type' header keywords to match
to ignore and skip decoding/indexing. For
all ignored parts, the content type will be
added to the indexed field
'body_ignored_content_types' (default
application,image)
--index-name Name of the index to store your messages
(default gmail)
--infile The mbox input file
--init Force deleting and re-initializing the
Elasticsearch index (default False)
--num-of-shards Number of shards for ES index (default 2)
--skip Number of messages to skip from the mbox
file (default 0)
导入 MBOX 电子邮件数据时，在日志输出中您可能会看到如下警告/错误。
它们是预期的并且没问题，它们只是关于某些无法解码的特殊字符的警告等。
...
/usr/lib/python2.7/site-packages/bs4/__init__.py:282: UserWarning: "https://someurl.com/whatever" looks like a URL. Beautiful Soup is not an HTTP client. You should probably use an HTTP client like requests to get the document behind the URL, and feed that document to Beautiful Soup.
' that document to Beautiful Soup.' % decoded_markup
[W 170825 18:41:56 dammit:381] Some characters could not be decoded, and were replaced with REPLACEMENT CHARACTER.
[W 170825 18:41:56 dammit:381] Some characters could not be decoded, and were replaced with REPLACEMENT CHARACTER.
...
工具箱中嵌入的 CSV 导入工具csv2es可以导入任何 CSV 文件，而不仅仅是下面的示例格式。
对于 CSV 文件中的每一行数据，每一行都成为 ElasticSearch 中的一个单独文档，其中所有 CSV 列都作为单独的字段进行索引
例如，导入到索引的下面的 CSV 数据文件（来自 iphone 的短信）中的每一行都有以下字段可用于在 Kibana 中搜索和分析
"Name","Address","date_ts","Message","Attachment","iMessage"
"Me","+1 555-555-5555","7/17/2016 9:21:39 AM","How are you doing?","","True"
"Joe Smith","+1 555-444-4444","7/17/2016 9:38:56 AM","Pretty good you?","","True"
"Me","+1 555-555-5555","7/17/2016 9:39:02 AM","Great!","","True"
....
上述短信导出CSV只是一个示例。与工具箱捆绑在一起的csv2es工具可以导入您想要的任何数据集，而不仅仅是上面的示例格式。
一旦 Docker 在您的系统上可用，在运行comms-analyzer-toolbox之前，您需要一些 CSV 格式的数据进行分析。作为示例，下面介绍如何将 iPhone 上的短信导出到 CSV 文件。
使用适用于 Mac 或 Windows 的 iExplorer 导出 iPhone 消息
编辑生成的CSV文件，将第一行的标题值"Time"更改为"date_ts" ，保存并退出。
记下.csv文件的位置，因为您将在下面运行工具箱时使用它。
在运行下面的示例之前，您需要安装 Docker。
下面的示例专门针对包含使用 IExplorer 导出的文本消息数据的 CSV 数据文件
data.csv 的内容
"Name","Address","date_ts","Message","Attachment","iMessage"
"Me","+1 555-555-5555","7/17/2016 9:21:39 AM","How are you doing?","","True"
"Joe Smith","+1 555-444-4444","7/17/2016 9:38:56 AM","Pretty good you?","","True"
"Me","+1 555-555-5555","7/17/2016 9:39:02 AM","Great!","","True"
....
csvdata.mapping.json 的内容
{
"dynamic": "true",
"properties": {
"date_ts": {"type": "date" },
"name": {"type": "string", "index" : "not_analyzed"},
"address": {"type": "string", "index" : "not_analyzed"},
"imessage": {"type": "string", "index" : "not_analyzed"}
}
}
在计算机上打开终端或命令提示符并运行以下命令，在此之前，您需要替换PATH/TO/YOUR/data.csv 、 PATH/TO/YOUR/csvdata.mapping.json和PATH/TO/ELASTICSEARCH_DATA_DIR下面根据需要添加本地系统上的正确路径。
注意：如果使用适用于 Windows 的 Docker Toolbox ：由于权限问题，下面所有已安装的卷都应位于c:Users[your username]...下的主目录下的某个位置。
docker run --rm -ti -p 5601:5601
-v PATH/TO/YOUR/data.csv:/toolbox/data.csv
-v PATH/TO/YOUR/csvdata.mapping.json:/toolbox/csvdata.mapping.json
-v PATH/TO/ELASTICSEARCH_DATA_DIR:/toolbox/elasticsearch/data
comms-analyzer-toolbox:latest
python /toolbox/csv2es/csv2es.py
[--existing-index ]
[--delete-index ]
--index-name comm_data
--doc-type txtmsg
--mapping-file /toolbox/csvdata.mapping.json
--import-file /toolbox/data.csv
--delimiter ','
--csv-clean-fieldnames
--csv-date-field date_ts
--csv-date-field-gmt-offset -1
如果针对预先存在的comm_data索引运行，请确保仅包含--existing-index标志。如果您想在导入之前重新创建comm_data索引，请仅包含--delete-index标志。
控制台将记录正在发生的情况的输出，当系统启动时，您可以在桌面上打开 Web 浏览器并转到http://localhost:5601开始使用 Kibana 分析数据。注意：如果运行 docker toolbox； ‘localhost’可能不起作用，执行docker-machine env default以确定您的 docker 主机 IP 地址，然后转到 http://[machine-ip]:5601”
在显示Configure an index pattern的第一个屏幕上，在标记为Index name or pattern字段中键入comm_data然后您将看到自动选择的date_ts字段，然后单击Create按钮。从那里 Kibana 就可以使用了！
启动按以下顺序执行几件事
当 mbox 导入程序运行时，您将在日志中看到以下条目，因为系统正在从 mbox 文件导入您的邮件
运行comms-analyzer-toolbox映像时，参数之一是调用采用以下参数的 csv2es 脚本。您可以根据需要调整上面的docker run命令以传递以下标志：
Usage: /toolbox/csv2es/csv2es.py [OPTIONS]
Bulk import a delimited file into a target Elasticsearch instance. Common
delimited files include things like CSV and TSV.
Load a CSV file:
csv2es --index-name potatoes --doc-type potato --import-file potatoes.csv
For a TSV file, note the tab delimiter option
csv2es --index-name tomatoes --doc-type tomato --import-file tomatoes.tsv --tab
For a nifty pipe-delimited file (delimiters must be one character):
csv2es --index-name pipes --doc-type pipe --import-file pipes.psv --delimiter '|'
Options:
--index-name TEXT Index name to load data into
[required]
--doc-type TEXT The document type (like user_records)
[required]
--import-file TEXT File to import (or '-' for stdin)
[required]
--mapping-file TEXT JSON mapping file for index
--delimiter TEXT The field delimiter to use, defaults to CSV
--tab Assume tab-separated, overrides delimiter
--host TEXT The Elasticsearch host
(http://127.0.0.1:9200/)
--docs-per-chunk INTEGER The documents per chunk to upload (5000)
--bytes-per-chunk INTEGER The bytes per chunk to upload (100000)
--parallel INTEGER Parallel uploads to send at once, defaults
to 1
--delete-index Delete existing index if it exists
--existing-index Don't create index.
--quiet Minimize console output
--csv-clean-fieldnames Strips double quotes and lower-cases all CSV
header names for proper ElasticSearch
fieldnames
--csv-date-field TEXT The CSV header name that represents a date
string to parsed (via python-dateutil) into
an ElasticSearch epoch_millis
--csv-date-field-gmt-offset INTEGER
The GMT offset for the csv-date-field (i.e.
+/- N hours)
--tags TEXT Custom static key1=val1,key2=val2 pairs to
tag all entries with
--version Show the version and exit.
--help Show this message and exit.
在此模式下运行只会启动 elasticsearch 和 kibana，不会导入任何内容。它只是打开工具箱，以便您可以分析之前导入的位于 elasticsearch 中的数据。
注意：如果使用适用于 Windows 的 Docker Toolbox ：由于权限问题，下面所有已安装的卷都应位于c:Users[your username]...下的主目录下的某个位置。
docker run --rm -ti -p 5601:5601
-v PATH/TO/ELASTICSEARCH_DATA_DIR:/toolbox/elasticsearch/data
comms-analyzer-toolbox:latest
analyze-only
想要控制默认的 ElasticSearch JVM 内存堆选项，您可以通过 docker 环境变量来实现，即-e ES_JAVA_OPTS="-Xmx1g -Xms1g"等。
对于hotmail/outlook，您需要导出到PST，然后作为第二步转换为MBOX
使用此工具对于您运行此工具的任何机器（即您的 Docker 主机）来说完全是本地的。如果在笔记本电脑或台式计算机上运行它，则它是 100% 本地的。
数据不会上传或传输到任何地方。
除了运行该数据的 Docker 主机本地磁盘上之外，数据不会传输到任何其他地方。
要完全删除分析的数据，您可以对计算机上运行的comms-analyzer-toolbox容器执行docker rm -f [container-id] 。
如果您通过主机上的卷安装了elasticsearch数据目录（即-v PATH/TO/ELASTICSEARCH_DATA_DIR:/toolbox/elasticsearch/data ），则本地目录是所有索引数据本地驻留在磁盘上的位置。
