diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 67b7fcdff..bcc8e3304 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,29 +1,31 @@ -This file serves as a supplement to the [HACKING file](HACKING). It contains -information specifically about Nmap's use of Github and how contributors can use -Github services to participate in Nmap development. +# Table of Contents +--- + + * [Introduction](#intro) + * [Code Repository](#repo) + * [Bug Reports](#bug) + * [Pull Requests](#pr) + * [issues.nmap.org redirector](#issues) + * [The HACKING file](#hacking) -## Code Repository +## Introduction -The authoritative code repository is still the Subversion repository at -https://svn.nmap.org/nmap . The Github repository is synchronized once per hour. -All commits are made directly to Subversion, so Github is a read-only mirror. +This file serves as a supplement to the [HACKING file](HACKING). It contains information specifically about Nmap's use of Github and how contributors can use Github services to participate in Nmap development. -## Bug Reports +## Code Repository -Nmap uses Github Issues to keep track of bug reports. Please be sure to include -the version of Nmap that you are using, steps to reproduce the bug, and a -description of what you expect to be the correct behavior. +The authoritative code repository is still the Subversion repository at [https://svn.nmap.org/nmap](https://svn.nmap.org/nmap). The Github repository is synchronized once per hour. All commits are made directly to Subversion, so Github is a read-only mirror. -## Pull Requests +## Bug Reports -Nmap welcomes your code contribution in the form of a Github Pull Request. Since -the Github repository is currently read-only, we cannot merge directly from the -PR. Instead, we will convert your PR into a patch and apply it to the Subversion -repository. We will be sure to properly credit you in the CHANGELOG file, and -the commit message will reference the PR number. +Nmap uses Github Issues to keep track of bug reports. Please be sure to include the version of Nmap that you are using, steps to reproduce the bug, and a description of what you expect to be the correct behavior. + +## Pull Requests + +Nmap welcomes your code contribution in the form of a Github Pull Request. Since the Github repository is currently read-only, we cannot merge directly from the PR. Instead, we will convert your PR into a patch and apply it to the Subversion repository. We will be sure to properly credit you in the CHANGELOG file, and the commit message will reference the PR number. Because not all Nmap committers use Github daily, it is helpful to send a -notification email to dev@nmap.org referencing the PR and including a short +notification email to [dev@nmap.org](mailto:dev@nmap.org) referencing the PR and including a short description of the functionality of the patch. Using pull requests has several advantages over emailed patches: @@ -34,18 +36,14 @@ Using pull requests has several advantages over emailed patches: changes. 3. Referencing contributions by PR number is more convenient than tracking by -seclists.org mail archive URL, especially when the discussion spans more than +[seclists.org](http://seclists.org/) mail archive URL, especially when the discussion spans more than one quarter year. -## issues.nmap.org redirector +## issues.nmap.org redirector -For convenience, you may use issues.nmap.org to redirect to issues (bug reports -and pull requests) by number (e.g. http://issues.nmap.org/34) or to link to the -new-issue page: http://issues.nmap.org/new +For convenience, you may use [issues.nmap.org](http://issues.nmap.org) to redirect to issues (bug reports and pull requests) by number (e.g. [http://issues.nmap.org/34](http://issues.nmap.org/34)) or to link to the new-issue page: [http://issues.nmap.org/new](http://issues.nmap.org/new). -## The HACKING file +## The HACKING file General information about hacking Nmap and engaging with our community of -developers and users can be found in the [HACKING file](HACKING). It describes -how to get started, licensing, style guidance, and how to use the dev mailing -list. +developers and users can be found in the [HACKING file](HACKING). It describes how to get started, licensing, style guidance, and how to use the dev mailing list. diff --git a/macosx/BUNDLING.md b/macosx/BUNDLING.md index 458a6f019..4608d34b5 100644 --- a/macosx/BUNDLING.md +++ b/macosx/BUNDLING.md @@ -1,15 +1,15 @@ -# Bundling +# Table of Contents +--- + + * [Jhbuild](#jhbuild) + * Observation + * Possible error + * [gtk-mac-bundler](#bundler) + * [How to use](#howto) + * Prerequisite + * Usage -## Notes - -This package contains Nmap, Zenmap, Ncat, Ndiff, and Nping. It is intended to work on Intel Macs running Mac OS X 10.8 or later. - -Installation of all packages is optional. Unselect Zenmap to get just the command-line tool. Unselect Nmap if you prefer to use a copy of Nmap that is already installed. Zenmap will not work without Nmap. - -The nmap, ncat, ndiff, and nping command-line binaries will be installed in `/usr/local/bin`, and additional support files will be installed in `/usr/local/share`. The Zenmap application bundle will be installed in `/Applications/Zenmap.app`. - - -## Jhbuild +## Jhbuild In order to set up Jhbuild properly before building Nmap suite, follow the tutorial at [https://wiki.gnome.org/Projects/GTK%2B/OSX/Building](https://wiki.gnome.org/Projects/GTK%2B/OSX/Building), but keep reading this file if you encounter any error... @@ -97,8 +97,7 @@ Now, add the path for the new SVN version to your _$PATH_: $ export PATH=/opt/subversion/bin:$PATH ~~~~ - -## Jhbuild & gtk-mac-bundler +## gtk-mac-bundler Now that Jhbuild is properly configured, we need to install **gtk-mac-bundler** in order to render the bundle file: @@ -108,7 +107,7 @@ $ cd gtk-mac-bundler $ make install ~~~~ -## How to use +## How to use #### Prerequisite: —`openssl.modules`: diff --git a/macosx/README b/macosx/README deleted file mode 100644 index 3d2b92dad..000000000 --- a/macosx/README +++ /dev/null @@ -1,7 +0,0 @@ -Nmap is a free and open source utility for network exploration and security auditing. Zenmap is a multi-platform graphical frontend and results viewer for Nmap. Ncat is a general-purpose network sending and receiving utility, a reimplementation of Netcat. Ndiff is a an Nmap scan comparison utility. Nping is a tool for packet generation and sending. - -This package contains Nmap, Zenmap, Ncat, Ndiff, and Nping. It is intended to work on Intel Macs running Mac OS X 10.8 or later. - -Installation of all packages is optional. Unselect Zenmap to get just the command-line tool. Unselect Nmap if you prefer to use a copy of Nmap that is already installed. Zenmap will not work without Nmap. - -The nmap, ncat, ndiff, and nping command-line binaries will be installed in /usr/local/bin, and additional support files will be installed in /usr/local/share. The Zenmap application bundle will be installed in /Applications/Zenmap.app. diff --git a/macosx/README.md b/macosx/README.md new file mode 100644 index 000000000..e0fa53346 --- /dev/null +++ b/macosx/README.md @@ -0,0 +1,96 @@ +# Table of Contents +--- + + * [Introduction](#intro) + * [Requirements](#requ) + * [Installation](#install) + * [Files in this directory](#files) + * [Zenmap](#zenmap) + * [Repositories and Troubleshooting](#repo) + * [The CONTRIBUTING file](#contributing) + +## Introduction + + * **Nmap** is a free and open source utility for network exploration and security auditing. + * **Zenmap** is a multi-platform graphical frontend and results viewer for Nmap. + * **Ncat** is a general-purpose network sending and receiving utility, a reimplementation of Netcat. + * **Ndiff** is a an Nmap scan comparison utility. + * **Nping** is a tool for packet generation and sending. + +This package contains Nmap, Zenmap, Ncat, Ndiff, and Nping. It is intended to work on Intel Macs running **Mac OS X 10.8 or later**. + +Installation of all packages is optional. Unselect Zenmap to get just the command-line tool. Unselect Nmap if you prefer to use a copy of Nmap that is already installed. Zenmap will not work without Nmap. + +The nmap, ncat, ndiff, and nping command-line binaries will be installed in `/usr/local/bin`, and additional support files will be installed in `/usr/local/share`. The Zenmap application bundle will be installed in `/Applications/Zenmap.app`. + +For a full description of Nmap's installation on Mac OS, visit the page: +[https://nmap.org/book/inst-macosx.html](https://nmap.org/book/inst-macosx.html) + +## Requirements + +In order to compile, build and run Nmap on Mac OS, you will requiere the followings: + +1. **Jhbuild** for bundling and dependencies (see the [BUNDLING file](../BUNDLING.md)) +2. **Xcode** for Mac OS 10.8 or later ([https://developer.apple.com/xcode](https://developer.apple.com/xcode/)) +3. **Xcode Command-line Tools** for Mac OS 10.8 or later ([https://developer.apple.com/downloads](https://developer.apple.com/downloads/) — then download the latest version compatible with your OS version) + +## Installation + +Ideally, you should be able to just type: + + ./configure + make + make install + +from `nmap/` directory (the root folder). + +For far more in-depth compilation, installation, and removal notes, read the **Nmap Install Guide** at [https://nmap.org/book/install.html](https://nmap.org/book/install.html). + +## Files in this directory + +* [openssl.modules](openssl.modules): This is a Jhbuild moduleset that can be used to build dependencies (openssl, libsvn and libapr) as required for building Nmap, Ncat, Nping and nmap-update. Use it like this: + + ~~~~ + $ jhbuild -m openssl.modules build nmap-deps + ~~~~ + +* [Makefile](Makefile): The Mac OS X Makefile used to build everything specific to this OS. +* [BUNDLING.md](BUNDLING.md): A manual on how to setup and use Jhbuild on Mac OS X. + +## Zenmap + +### Files into `zenmap/install_scripts/macosx/`: + +All of the files have to do with packaging on Mac OS X. They are useful only for those wanting to build binary distributions of Zenmap for Mac OS X. + +* [Info.plist](../zenmap/install_scripts/macosx/Info.plist): A properties list file template that is filled out by [make-bundle.sh](../zenmap/install_scripts/macosx/make-bundle.sh). +* [make-bundle.sh](../zenmap/install_scripts/macosx/make-bundle.sh): This script builds a .app bundle. It must be run from the root of the Zenmap source tree. The finished bundle is put in `dist/Zenmap.app`. +* [zenmap.icns](../zenmap/install_scripts/macosx/zenmap.icns): The icon file for the bundle. It was created using the Icon Composer utility (`$ open -a "Icon Composer"`). +* [zenmap_auth.c](../zenmap/install_scripts/macosx/zenmap_auth.c): This is a simple wrapper program that attempts to run [launcher.sh](../zenmap/install_scripts/macosx/launcher.sh) with privileges. +* [launcher.sh](../zenmap/install_scripts/macosx/launcher.sh): A launcher script that configures the environment for Zenmap, Python, and GTK before launching the main Zenmap script file. +* [zenmap.bundle](../zenmap/install_scripts/macosx/zenmap.bundle): An XML configuration file for gtk-mac-bundler which specifies files and metadata for the application bundle ([https://wiki.gnome.org/Projects/GTK%2B/OSX/Building](https://wiki.gnome.org/Projects/GTK%2B/OSX/Building)). + +### Authorization Wrapper: + +The **bundling** process is as follows: + +1. First, the bundler ([make-bundle.sh](../zenmap/install_scripts/macosx/make-bundle.sh)) look at the bundle XML (`zenmap.bundle`) and copy everything over. +2. The launcher script ([launcher.sh](../zenmap/install_scripts/macosx/launcher.sh)) gets renamed into the app name (`Zenmap`). +3. The authorization wrapper is compiled to `Zenmap` so that it is the entry point of the app. +4. The last part is filling in the [Info.plist template file](../zenmap/install_scripts/macosx/Info.plist) based on the current information in `zenmap.ZenmapCore.Version`. + +After the bundling process is done and the app is installed, the **execution** path is as follows: + +**Zenmap (zenmap_auth) —> zenmap.bin (launcher.sh) —> python zenmap.py** + +## Repositories and Troubleshooting + +Nmap uses a read-only repository on **Github** for issues tracking and pull requests. You can contribute at the following address: [https://github.com/nmap/nmap](https://github.com/nmap/nmap). + +The read-write repository is managed with **Subversion**. Although, all actual commits are made to our Subversion repository on [https://svn.nmap.org](https://svn.nmap.org/). + +In order to be always up to date, you can consult the Changelog here: [https://nmap.org/changelog.html](https://nmap.org/changelog.html). + +## The CONTRIBUTING file + +General information about contributing to Nmap can be found in the [CONTRIBUTING file](../CONTRIBUTING.md). It contains information specifically about Nmap's use of Github and how contributors can use Github services to participate in **Nmap development**. \ No newline at end of file