Skip to content

Commit f505aad

Browse files
thehappydinoathehappydinoa
committed
chore(docs): Update docs to include new APIs
1 parent e52b08c commit f505aad

File tree

11 files changed

+197
-148
lines changed

11 files changed

+197
-148
lines changed

‎.flake8‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ exclude =
1414
per-file-ignores =
1515
tests/*.py:E501,D100,D101,D102,D103,D104,D107,
1616
__init__.py:F401,F403,
17+
examples/*.py:E402
1718
censys/search/v2/certs.py:DAR101
1819
docstring-convention = google
1920
docstring_style = google

‎docs/usage-v2.rst‎

Lines changed: 32 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ Usage v2
33

44
The Censys Search API provides functionality for interacting with Censys resources such as Hosts.
55

6-
There are three API options that this library provides access to:
6+
There are three main API endpoints that this library provides access to:
77

88
- :attr:`search <censys.search.v2.api.CensysSearchAPIv2.search>` - Allows searches against the Hosts index using the same search syntax as the `web app <https://search.censys.io/search/language?resource=hosts>`__.
99
- :attr:`view <censys.search.v2.api.CensysSearchAPIv2.view>` - Returns the structured data we have about a specific Host, given the resource's natural ID.
@@ -23,173 +23,83 @@ Python class objects must be initialized for each resource index (Hosts).
2323
``search``
2424
----------
2525

26-
Below we show an example using the :attr:`CensysHosts <censys.search.v2.CensysHosts>` index.
27-
28-
.. code:: python
29-
30-
#!/usr/bin/env python3
31-
from censys.search import CensysHosts
32-
33-
h = CensysHosts()
34-
35-
# Single page of search results
36-
query = h.search("service.service_name: HTTP", per_page=5)
37-
print(query())
26+
**Please note this method is only available only for the CensysHosts index.**
3827

39-
# Multiple pages of search results
40-
# You can optionally pass in a number of results to be returned
41-
# each page and the number of pages you want returned.
42-
for page in h.search("service.service_name: HTTP", per_page=5, pages=2):
43-
print(page)
44-
45-
# You can also get all pages of results by using -1 for pages
46-
for page in h.search("service.service_name: HTTP", pages=-1):
47-
print(page)
28+
Below we show an example using the :attr:`CensysHosts <censys.search.v2.CensysHosts>` index.
4829

49-
# View each result returned
50-
# For `hosts` this looks like a mapping of IPs to view results
51-
query = h.search("service.service_name: HTTP", per_page=5, pages=2)
52-
print(query.view_all())
30+
.. include:: ../examples/search/search_hosts.py
31+
:literal:
5332

5433
``view``
5534
--------
5635

57-
Below we show an example using the :attr:`CensysHosts <censys.search.v2.CensysHosts>` index.
36+
**Please note this method is only available only for the CensysHosts index.**
5837

59-
.. code:: python
38+
Below we show an example using the :attr:`CensysHosts <censys.search.v2.CensysHosts>` index.
6039

61-
from censys.search import CensysHosts
40+
.. include:: ../examples/search/view_host.py
41+
:literal:
6242

63-
h = CensysHosts()
64-
65-
# Fetch a specific host and its services
66-
host = h.view("8.8.8.8")
67-
print(host)
43+
``bulk_view``
44+
-------------
6845

69-
# You can optionally pass in a RFC3339 timestamp to
70-
# fetch a host at the given point in time.
71-
# Please note historical API access is required.
72-
host = h.view("8.8.8.8", at_time="2021-03-01T17:49:05Z")
73-
print(host)
46+
**Please note this method is only available only for the CensysHosts index.**
7447

75-
# You can also pass in a date or datetime object.
76-
from datetime import date
48+
Below we show an example using the :attr:`CensysHosts <censys.search.v2.CensysHosts>` index.
7749

78-
host = h.view("8.8.8.8", at_time=date(2021, 3, 1))
79-
print(host)
50+
.. include:: ../examples/search/bulk_view_hosts.py
51+
:literal:
8052

8153
``aggregate``
8254
-------------
8355

84-
Below we show an example using the :attr:`CensysHosts <censys.search.v2.CensysHosts>` index.
85-
86-
.. code:: python
87-
88-
from censys.search import CensysHosts
56+
**Please note this method is only available only for the CensysHosts index.**
8957

90-
h = CensysHosts()
58+
Below we show an example using the :attr:`CensysHosts <censys.search.v2.CensysHosts>` index.
9159

92-
# The aggregate method constructs a report using a query, an aggregation field, and the
93-
# number of buckets to bin.
94-
report = h.aggregate(
95-
"service.service_name: HTTP",
96-
"services.port",
97-
num_buckets=5,
98-
)
99-
print(report)
60+
.. include:: ../examples/search/aggregate_hosts.py
61+
:literal:
10062

10163
``metadata``
10264
-------------
10365

104-
**Please note this method is only available only for the CensysHosts index**
66+
**Please note this method is only available only for the CensysHosts index.**
10567

10668
Below we show an example using the :attr:`CensysHosts <censys.search.v2.CensysHosts>` index.
10769

108-
.. code:: python
109-
110-
from censys.search import CensysHosts
111-
112-
h = CensysHosts()
113-
114-
# Fetch metadata about hosts.
115-
meta = h.metadata()
116-
print(meta.get("services"))
70+
.. include:: ../examples/search/metadata_hosts.py
71+
:literal:
11772

11873
``view_host_names``
11974
-------------------
12075

121-
**Please note this method is only available only for the CensysHosts index**
76+
**Please note this method is only available only for the CensysHosts index.**
12277

12378
Below we show an example using the :attr:`CensysHosts <censys.search.v2.CensysHosts>` index.
12479

125-
.. code:: python
126-
127-
from censys.search import CensysHosts
128-
129-
h = CensysHosts()
130-
131-
# Fetch a list of host names for the specified IP address.
132-
names = h.view_host_names("1.1.1.1")
133-
print(names)
80+
.. include:: ../examples/search/view_host_names.py
81+
:literal:
13482

13583
``view_host_events``
13684
--------------------
13785

138-
**Please note this method is only available only for the CensysHosts index**
86+
**Please note this method is only available only for the CensysHosts index.**
13987

14088
Below we show an example using the :attr:`CensysHosts <censys.search.v2.CensysHosts>` index.
14189

142-
.. code:: python
143-
144-
from censys.search import CensysHosts
145-
146-
h = CensysHosts()
147-
148-
# Fetch a list of events for the specified IP address.
149-
events = h.view_host_events("1.1.1.1")
150-
print(events)
151-
152-
# You can also pass in a date or datetime objects.
153-
from datetime import date
154-
155-
events = h.view_host_events(
156-
"1.1.1.1", start_time=date(2021, 7, 1), end_time=date(2021, 7, 31)
157-
)
158-
print(events)
90+
.. include:: ../examples/search/view_host_events.py
91+
:literal:
15992

16093
``view_host_diff``
16194
------------------
16295

163-
**Please note this method is only available only for the CensysHosts index**
96+
**Please note this method is only available only for the CensysHosts index.**
16497

16598
Below we show an example using the :attr:`CensysHosts <censys.search.v2.CensysHosts>` index.
16699

167-
.. code:: python
168-
169-
from censys.search import CensysHosts
170-
171-
h = CensysHosts()
172-
173-
# Compare a single host between two timestamps
174-
diff = c.view_host_diff("1.1.1.1", at_time=date(2022, 1, 1), at_time_b=date(2022, 1, 2))
175-
print(diff)
100+
.. include:: ../examples/search/view_host_diff.py
101+
:literal:
176102

177-
# Compare a single host between its current timestamp and a timestamp
178-
diff = c.view_host_diff("1.1.1.2", at_time=date(2022, 1, 2))
179-
print(diff)
180-
181-
# Compare two hosts
182-
diff = c.view_host_diff("1.1.1.1", ip_b="1.1.1.2")
183-
print(diff)
184-
185-
# Compare two hosts between two timestamps
186-
diff = c.view_host_diff(
187-
"1.1.1.1",
188-
ip_b="1.1.1.2",
189-
at_time=date(2022, 1, 1),
190-
at_time_b=date(2022, 1, 2),
191-
)
192-
print(diff)
193103

194104
``get_hosts_by_cert``
195105
---------------------
@@ -427,7 +337,7 @@ Below we show an example using the :attr:`CensysCerts <censys.search.v2.CensysCe
427337
``list_hosts_with_tag``
428338
^^^^^^^^^^^^^^^^^^^^^^^
429339

430-
**Please note this method is only available only for the CensysHosts index**
340+
**Please note this method is only available only for the CensysHosts index.**
431341

432342
Below we show an example using the :attr:`CensysHosts <censys.search.v2.CensysHosts>` index.
433343

‎examples/README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,14 @@ For our package import statements are structured like this.
99
### Search
1010

1111
```python
12+
# Access all indexes
1213
from censys.search import SearchClient
14+
15+
# Access only the hosts index
16+
from censys.search import CensysHosts
17+
18+
# Access only the certificates index
19+
from censys.search import CensysCertificates
1320
```
1421

1522
### ASM
@@ -23,10 +30,20 @@ from censys.asm import AsmClient
2330
### Search Examples
2431

2532
- [Using `SearchClient`](search/search_client.py)
33+
34+
#### Hosts Index
35+
2636
- [View Host](search/view_host.py)
2737
- [Search Hosts](search/search_hosts.py)
2838
- [Aggregate Hosts](search/aggregate_hosts.py)
2939
- [Bulk View Hosts](search/bulk_view_hosts.py)
40+
- [Hosts Metadata](search/metadata_hosts.py)
41+
- [View Host Events](search/view_host_events.py)
42+
- [View Host Names](search/view_host_names.py)
43+
- [View Host Diff](search/view_host_diff.py)
44+
45+
#### Certificates Index
46+
3047
- [View Certificate](search/view_cert.py)
3148
- [Search Certificates](search/search_certs.py)
3249
- [Report Certificates](search/report_certs.py)

‎examples/search/aggregate_hosts.py‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,17 @@
1111
num_buckets=5,
1212
)
1313
print(report)
14+
# {
15+
# "total": 987342156,
16+
# "total_omitted": 836949090,
17+
# "potential_deviation": 3965103,
18+
# "buckets": [
19+
# {"key": "80", "count": 58727150},
20+
# {"key": "443", "count": 46716751},
21+
# {"key": "7547", "count": 19185117},
22+
# {"key": "22", "count": 13276559},
23+
# {"key": "30005", "count": 12487489},
24+
# ],
25+
# "query": "service.service_name: HTTP",
26+
# "field": "services.port",
27+
# }

‎examples/search/metadata_hosts.py‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
"""Metadata on the hosts index."""
2+
from censys.search import CensysHosts
3+
4+
h = CensysHosts()
5+
6+
# Fetch metadata about hosts.
7+
meta = h.metadata()
8+
print(meta)
9+
# {
10+
# "services": [
11+
# "DNS",
12+
# "FTP",
13+
# "HTTP",
14+
# "POP3",
15+
# "SMTP",
16+
# "SSH",
17+
# ...
18+
# ]
19+
# }

‎examples/search/search_client.py‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,12 @@
33

44
c = SearchClient()
55

6-
# v1
7-
certs = c.v1.certificates # or c.v1.certs
6+
# v2 indexes
7+
hosts = c.v2.hosts # Same as hosts = CensysHosts()
88

9-
data = c.v1.data
9+
hosts.view("")
1010

11-
# v2
12-
hosts = c.v2.hosts
11+
# v1 indexes
12+
certs = c.v1.certificates # Same as certs = CensysCertificates()
13+
14+
data = c.v1.data # Same as data = CensysData()

‎examples/search/search_hosts.py‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,21 @@
11
"""Search hosts data set."""
2-
from censys.search import SearchClient
2+
from censys.search import CensysHosts
33

4-
c = SearchClient()
4+
h = CensysHosts()
55

66
# Single page of search results
7-
query = c.v2.hosts.search("service.service_name: HTTP", per_page=5)
7+
query = h.search("service.service_name: HTTP", per_page=5)
88
print(query())
99

1010
# Multiple pages of search results
11-
query = c.v2.hosts.search("service.service_name: HTTP", per_page=5, pages=2)
11+
query = h.search("service.service_name: HTTP", per_page=5, pages=2)
1212
for page in query:
1313
print(page)
1414

1515
# View all results
16-
query = c.v2.hosts.search("service.service_name: HTTP", per_page=5, pages=2)
16+
query = h.search("service.service_name: HTTP", per_page=5, pages=2)
1717
print(query.view_all())
1818

1919
# Search for virtual hosts
20-
query = c.v2.hosts.search(
21-
"NOT services.service_name: HTTP", per_page=5, virtual_hosts="ONLY"
22-
)
20+
query = h.search("NOT services.service_name: HTTP", per_page=5, virtual_hosts="ONLY")
2321
print(query())

0 commit comments

Comments
 (0)