From 9edff4898da121b4ab7d7aef8b6f49a45de1fc87 Mon Sep 17 00:00:00 2001
From: 4shen0ne <4shen.01@gmail.com>
Date: Sun, 20 Oct 2024 00:45:37 +0800
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20update=20documents?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/index.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++--
docs/masscan.md | 2 ++
docs/model.md | 1 +
docs/nmap.md | 2 ++
mkdocs.yml | 7 +++++-
5 files changed, 68 insertions(+), 3 deletions(-)
create mode 100644 docs/model.md
diff --git a/docs/index.md b/docs/index.md
index 52979fd..cccd704 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,8 +1,63 @@
-# nmass
+# Nmass
[![Release](https://img.shields.io/github/v/release/zrquan/nmass)](https://img.shields.io/github/v/release/zrquan/nmass)
[![Build status](https://img.shields.io/github/actions/workflow/status/zrquan/nmass/main.yml?branch=main)](https://github.com/zrquan/nmass/actions/workflows/main.yml?query=branch%3Amain)
[![Commit activity](https://img.shields.io/github/commit-activity/m/zrquan/nmass)](https://img.shields.io/github/commit-activity/m/zrquan/nmass)
[![License](https://img.shields.io/github/license/zrquan/nmass)](https://img.shields.io/github/license/zrquan/nmass)
-A python3 library that makes it easier to use nmap and masscan.
+Nmass is a python3 library that makes it easier for developers to use **nmap and masscan**. It translates many and complex arguments into idiomatic methods and wraps the scan results in well-defined **pydantic** models.
+
+## Examples
+
+### Basic nmap example
+
+```python
+# nmap_example.py
+nm = (
+ Nmap()
+ .with_targets("172.18.0.2")
+ .with_most_common_ports(100)
+ .with_service_info()
+ .with_default_script()
+ .without_ping()
+ .without_dns_resolution()
+)
+if result := nm.run(with_output=False):
+ print(result.model_dump_json(exclude_none=True))
+```
+
+### Basic masscan example
+
+```python
+# masscan_example.py
+ms = (
+ Masscan()
+ .with_targets("183.2.172.185")
+ .with_ports("80,443")
+ .with_banner()
+)
+if result := ms.run(with_output=False):
+ print(result.model_dump_json(exclude_none=True))
+```
+
+### More?
+
+Masscan is fast, and nmap is powerful. Why not combine the two?🤩 Start by using masscan to quickly detect open ports in bulk, then use nmap to perform in-depth scans on these open ports!
+
+```python
+# This is just an example, is not recommended to run
+step1 = (
+ Masscan()
+ .with_targets("10.0.0.0/8")
+ .with_ports(80, 443)
+ .with_rate(10000)
+)
+step2 = (
+ Nmap()
+ .with_step(step1.run())
+ .with_service_info()
+ .with_scripts("http-title")
+ .with_verbose()
+)
+retult = step2.run()
+```
diff --git a/docs/masscan.md b/docs/masscan.md
index 41be6c8..540ceb6 100644
--- a/docs/masscan.md
+++ b/docs/masscan.md
@@ -1 +1,3 @@
::: nmass.masscan
+ options:
+ show_source: False
diff --git a/docs/model.md b/docs/model.md
new file mode 100644
index 0000000..5e53135
--- /dev/null
+++ b/docs/model.md
@@ -0,0 +1 @@
+::: nmass.model.elements
diff --git a/docs/nmap.md b/docs/nmap.md
index a167700..f5df59b 100644
--- a/docs/nmap.md
+++ b/docs/nmap.md
@@ -1 +1,3 @@
::: nmass.nmap
+ options:
+ show_source: False
diff --git a/mkdocs.yml b/mkdocs.yml
index 874e570..6ee34a1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -5,18 +5,21 @@ site_description: A python3 library that makes it easier to use nmap and masscan
site_author: zrquan
edit_uri: edit/main/docs/
repo_name: zrquan/nmass
-copyright: Maintained by Florian.
+copyright: Maintained by zrquan.
nav:
- Home: index.md
- Nmap: nmap.md
- Masscan: masscan.md
+ - Models: model.md
plugins:
- search
- mkdocstrings:
handlers:
python:
paths: [nmass]
+ options:
+ docstring_style: sphinx
theme:
name: material
feature:
@@ -51,3 +54,5 @@ markdown_extensions:
permalink: true
- pymdownx.arithmatex:
generic: true
+ - codehilite:
+ css_class: highlight