Merge branch 'master' into master

Author: sebdraven

.gitignore

@@ -87,3 +87,6 @@ ENV/
 
 # Rope project settings
 .ropeproject
+
+
+.idea/*

LICENSE renamed to LICENSE.md

@@ -1,9 +1,31 @@
-# pyeti
-Python bindings for Yeti's API
+# pyeti-python3
+Pyeti-Python (pyeti) is the bundle uses to interface with the YETI API. This is the new package that can be installed directly with pip.
+Pyeti-python allows you to extract data from YETI such as specific observables (malware, IP, domains...). It can be used to plug in your own tool and enrich your Threat Intelligence feed with Yeti.
 
-## Installation
+## Getting Started
+To install it you can clone the repo and run the following command:
 
-`$ python3 setup.py install` should get you started. After this gets a little more maturity, we will submit it to Pypy for usage with `pip`.
+```
+$ python3 setup.py install
+```
+
+You can also install it with pip:
+```
+$ pip3 install pyeti-python3
+``` 
+
+Once installed the first thing to do is to get your API key from the Yeti interface.
+<img src="https://raw.githubusercontent.com/fr0gger/pyeti/master/yeti_api.png">
+
+Then you can configure your script with the following information to test the connection:
+```python
+server="<IPofYETI>"
+key="<APIKEY>"
+tag="<NameoftheObservable>" # example: 'lokibot'
+
+api = pyeti.YetiApi("http://%s:5000/api/" % server, api_key=key)
+request = api.observable_search(tags=tag, count=50)
+```
 
 ## Testing
 
@@ -14,22 +36,21 @@ You can run tests from the root directory by running:
 
 **Note that most tests require a full running install of Yeti on localhost:5000**
 
-## Some examples
+## Use cases
 
 First thing is to import the library and instantiate a client.
 
 ```python
 import pyeti, json    # json is only used for pretty printing in the examples below 
-api = pyeti.YetiApi("http://localhost:5000/api/")
+api = pyetix.YetiApi("http://localhost:5000/api/")
 ```
 
-If you are using a self signed cert on your yeti instance you can set the `verify_ssl` parameter to `True` to false to ignore warnings.
+If you are using a self signed cert on your yeti instance you can set the `verify_ssl` parameter to `True` to ignore warnings.
 Otherwise all ssl connections are verified by default.
 
 ```python
 import pyeti, json    # json is only used for pretty printing in the examples below 
 api = pyeti.YetiApi("http://localhost:5000/api/", verify_ssl=False)
-
 ```
 
 
@@ -38,52 +59,14 @@ api = pyeti.YetiApi("http://localhost:5000/api/", verify_ssl=False)
 ```python
 results = api.observable_add("google.com", ['google'])
 print(json.dumps(results, indent=4, sort_keys=True))
-{
-    "context": [],
-    "created": "2017-06-25T17:33:51.735000",
-    "description": null,
-    "human_url": "http://localhost:5000/observable/594ff3ffbf365e53fbae38c9",
-    "id": "594ff3ffbf365e53fbae38c9",
-    "last_analyses": {},
-    "sources": [
-        "API"
-    ],
-    "tags": [
-        {
-            "first_seen": "2017-06-25T17:33:51.746000",
-            "fresh": true,
-            "last_seen": "2017-06-25T17:33:51.746000",
-            "name": "google"
-        }
-    ],
-    "type": "Hostname",
-    "url": "http://localhost:5000/api/observable/594ff3ffbf365e53fbae38c9",
-    "value": "google.com"
-}
 ```
-
 ### Bulk add
 
 ```python
 results = api.observable_bulk_add(["google.com", "bing.com", "yahoo.com"])
 print(len(results))
 3
 print(json.dumps(results[1], indent=4, sort_keys=True))
-{
-    "context": [],
-    "created": "2017-06-25T17:39:31.051000",
-    "description": null,
-    "human_url": "http://localhost:5000/observable/594ff553bf365e53fbae38cc",
-    "id": "594ff553bf365e53fbae38cc",
-    "last_analyses": {},
-    "sources": [
-        "API"
-    ],
-    "tags": [],
-    "type": "Hostname",
-    "url": "http://localhost:5000/api/observable/594ff553bf365e53fbae38cc",
-    "value": "bing.com"
-}
 ```
 
 ### Get a single observable
@@ -93,28 +76,6 @@ results = api.observable_add("google.com")
 print(results['id'])
 info = api.observable_details(results['id'])
 print(json.dumps(info, indent=4, sort_keys=True))
-{
-    "context": [],
-    "created": "2017-06-25T17:33:51.735000",
-    "description": null,
-    "human_url": "http://localhost:5000/observable/594ff3ffbf365e53fbae38c9",
-    "id": "594ff3ffbf365e53fbae38c9",
-    "last_analyses": {},
-    "sources": [
-        "API"
-    ],
-    "tags": [
-        {
-            "first_seen": "2017-06-25T17:33:51.746000",
-            "fresh": true,
-            "last_seen": "2017-06-25T17:33:51.746000",
-            "name": "google"
-        }
-    ],
-    "type": "Hostname",
-    "url": "http://localhost:5000/api/observable/594ff3ffbf365e53fbae38c9",
-    "value": "google.com"
-}
 ```
 
 ### Search for observables
@@ -123,75 +84,17 @@ print(json.dumps(info, indent=4, sort_keys=True))
 api.observable_add("search-domain.com")
 result = api.observable_search(value="search-dom[a-z]+", regex=True)
 print(json.dumps(result, indent=4, sort_keys=True))
-[
-    {
-        "context": [],
-        "created": "2017-06-25T17:57:28.994000",
-        "description": null,
-        "human_url": "http://localhost:5000/observable/594ff988bf365e58c4c2b8ef",
-        "id": "594ff988bf365e58c4c2b8ef",
-        "last_analyses": {},
-        "sources": [
-            "API"
-        ],
-        "tags": [],
-        "type": "Hostname",
-        "url": "http://localhost:5000/api/observable/594ff988bf365e58c4c2b8ef",
-        "value": "search-domain.com"
-    }
-]
-
 ```
 
-### Add files
-
+### Add observables
 ```python
 result = api.observable_file_add("/tmp/hello.txt", tags=['benign'])
 print(json.dumps(result, indent=4, sort_keys=True))
-[
-    {
-        "context": [],
-        "created": "2017-06-25T18:23:02.471000",
-        "description": null,
-        "hashes": [
-            {
-                "hash": "sha256",
-                "value": "b22b009134622b6508d756f1062455d71a7026594eacb0badf81f4f677929ebe"
-            },
-            {
-                "hash": "sha512",
-                "value": "eb22d991d6d86641d95e01a804025fc210491286a30f3114dd1469c7457c03e807506f5615bc9065f47a6ee2208364f643837f2298738b4f5c53797124f41f60"
-            },
-            {
-                "hash": "md5",
-                "value": "e134ced312b3511d88943d57ccd70c83"
-            },
-            {
-                "hash": "sha1",
-                "value": "a8d191538209e335154750d2df575b9ddfb16fc7"
-            }
-        ],
-        "human_url": "http://localhost:5000/observable/594fff86bf365e6270f8914b",
-        "id": "594fff86bf365e6270f8914b",
-        "last_analyses": {},
-        "mime_type": "text/plain",
-        "sources": [],
-        "tags": [
-            {
-                "first_seen": "2017-06-25T18:23:02.544000",
-                "fresh": true,
-                "last_seen": "2017-06-25T18:23:02.544000",
-                "name": "benign"
-            }
-        ],
-        "type": "File",
-        "url": "http://localhost:5000/api/observable/594fff86bf365e6270f8914b",
-        "value": "FILE:b22b009134622b6508d756f1062455d71a7026594eacb0badf81f4f677929ebe"
-    }
-]
 # Get file contents
 api.observable_file_contents(objectid="594fff86bf365e6270f8914b")
 'Hello!\n'
 api.observable_file_contents(filehash="e134ced312b3511d88943d57ccd70c83") # you can also use any hash computed above
 'Hello!\n'
 ```
+# License
+This project is licensed under the Apache License - see the [LICENSE.md](https://github.com/fr0gger/pyeti/blob/master/LICENSE.md) file for details